The 16-question AI readiness assessment (four areas: strategy, people, data, change; 15 questions scored). Ask the user each question, then call score_ai_readiness with the answers.
| Name | Required | Description | Default |
|---|---|---|---|
| section | No | Optional: return just one section's questions |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds genuinely useful context beyond those annotations: that the tool is meant for interactive use with the user, the four assessment areas, and that only 15 of the 16 questions are scored.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler: the first states what the tool returns and the assessment structure, the second gives the required next action. The content is front-loaded and every word serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one optional parameter and no output schema, the description plus schema is sufficient. It explains the assessment composition, the intended user interaction, and the follow-up call. It doesn't specify the shape of the returned questions, but the instruction to ask the user each question makes the purpose clear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully documents the optional 'section' parameter with enum values and a description, so schema coverage is high. The description enriches the enum values by mapping them to the four assessment areas and referencing the question count, but it does not introduce meaning the schema lacks. Baseline 3 is appropriate because the description adds only modest context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as returning a 16-question AI readiness assessment organized into four named areas. It also distinguishes the tool from the sibling score_ai_readiness by explaining the intended relationship. The minor 16-vs-15 scored question discrepancy is the only slight ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives an explicit workflow: ask the user each question, then call score_ai_readiness with the answers. This tells the agent exactly when and how to use the tool, and names the sibling that should be invoked next. It effectively prevents confusion with the scoring tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.
Each tool has a clearly distinct purpose: retrieving assessment questions, scoring assessment answers, listing services, retrieving case studies, searching resources, and providing contact info. The only related pair—get_ai_readiness_questions and score_ai_readiness—are complementary rather than overlapping, with one delivering the questions and the other processing the answers.
All tool names follow a consistent snake_case verb_noun pattern: get, list, score, and search. The naming style is uniform and predictable, making it easy for an agent to infer behavior from the tool name alone.
Six tools is a well-scoped size for a company information and readiness-assessment server. Each tool contributes a distinct function with no redundancy, and the count is comfortably within the ideal range.
The tool surface covers the server's apparent purpose comprehensively: services, case studies, resources, contact information, and a complete AI readiness assessment flow. The explicit note that the server has no write tools appropriately sets expectations, and users can obtain URLs/markdown for deeper content.