Inspiration

Dense corporate writing, unexplained acronyms, and images with no alt text are a constant, low-grade accessibility tax that most people never notice paying—or causing. We wanted something that surfaces the cost in the exact place it happens (a Slack message, mid-conversation) rather than as a separate audit tool nobody opens.

What it does

Cleary reviews Slack content on request and checks four things:

• Readability (Flesch-Kincaid grade level)
• Jargon and unexplained acronyms
• Missing image alt text
• Cognitive load issues that specifically affect dyslexic and ADHD readers (walls of text, shouting, no structure, and no summary)

When it finds something worth fixing, it proposes an actual restructured rewrite—not just a rephrase—with Copy rewrite and Post rewrite buttons. It never posts or edits anything without an explicit human click.

How we built it

The required hackathon technology was MCP server integration, so we built Cleary strictly around that architecture:

• Slack is the host application.
• A Bolt for Python agent acts as the MCP client.
• The four accessibility checks live in a separate custom MCP server, cleary-mcp, built with the official Python MCP SDK.
• The agent starts cleary-mcp as a subprocess over stdio.
• It discovers available tools by listing them and converts their JSON schemas into function declarations for the reasoning model.
• Gemini 2.5 Flash on Vertex AI decides when to call each tool.
• Tool results flow back to Gemini, which produces the final response.
• The response is streamed into Slack as visible task-card steps.
• An impact line is computed directly from the structured tool output (rather than relying on model phrasing).
• When appropriate, Cleary includes a rewrite with human approval buttons built using Slack Block Kit.

Challenges we ran into

We originally built the reasoning layer around Claude, matching the "receive input → reason (Claude) → call MCP tools" architecture from our original design.

Partway through development we hit an Anthropic billing limit, so rather than pay for a hackathon project we pivoted to Gemini on Vertex AI, authenticated through gcloud Application Default Credentials instead of an API key.

That required rewriting the tool-calling loop to use Gemini's function-calling format (Schema.from_json_schema) instead of Claude's tool-use blocks.

It reinforced an important lesson: the MCP layer is what provides portability. Swapping the reasoning model required very little change to the MCP server itself.

Accomplishments that we're proud of

• Building a complete, working MCP tool-use loop end to end.
• Having Gemini intelligently decide when to call tools like readability_score versus cognitive_load_check.
• Executing those tools against a live MCP subprocess and feeding structured results back into the reasoning model.
• Producing rewrites that genuinely restructure content—with headings, bullets, reduced shouting, and a TL;DR—instead of simply replacing words with simpler alternatives.

What we learned

We learned that much of "the agent" is actually the MCP client's plumbing rather than the LLM prompt.

Schema conversion, subprocess lifecycle management, and tool result formatting had a much bigger impact on building a reliable demo than prompt engineering did.

What's next

• Add the message.channels scope so Cleary can proactively flag accessibility issues in channels it's invited to, instead of only responding on request.
• Replace the current heuristic-based jargon and cognitive load checks with more sophisticated readability and accessibility models.

Built With

• a11y
• accessibility
• adhd
• agent-for-good
• ai-agent
• dyslexia
• gemini
• google-cloud
• llm
• mcp
• model-context-protocol
• natural-language-processing
• plain-language
• python
• readability
• slack
• slack-bolt
• socket
• textstat
• vertex-ai