AXIS Toolbox — Agentic Commerce Codebase Intelligence

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Description discloses authorization requirement ('Requires Authorization: Bearer <api_key>') and return value summary ('Returns snapshot_id plus artifact listing'). Does not contradict annotations (idempotentHint=true, destructiveHint=false, readOnlyHint=false). Additional behavioral context would include rate limits or error conditions, but what's provided is solid.

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?

Description is four short sentences, front-loaded with main purpose. Every sentence adds necessary information: purpose, return value, auth requirement, and alternatives. No redundant or irrelevant text.

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 complex tool (5 required params, output schema exists), description covers purpose, usage context, auth, and alternatives. Could mention output schema availability or limitations like file size, but the provided information is sufficient for basic usage. Output schema handles return value details.

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?

Input schema has 100% description coverage for all 5 parameters. Description does not add any parameter-specific guidance beyond what schema already provides. No value added for parameter semantics.

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?

Description clearly specifies verb 'analyze', resource 'source files', and outcome 'generate full 99-artifact AXIS bundle'. Distinguishes from siblings by stating 'use analyze_repo for GitHub URLs or improve_my_agent_with_axis for recommendation-first agent hardening'.

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?

Explicitly states when to use this tool: 'for local, generated, or unsaved code'. Provides explicit alternatives for other cases: analyze_repo for GitHub URLs, improve_my_agent_with_axis for recommendation-first. No ambiguity.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond annotations (idempotentHint=true, destructiveHint=false, readOnlyHint=false), the description reveals returned items (snapshot_id, artifacts), complementary tools (get_artifact, get_snapshot), pricing ($0.50/$0.15), and possible errors (authentication, quota, payment-required, etc.). This adds significant context for safe invocation.

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?

The description is a single paragraph that efficiently covers purpose, usage, pricing, errors, and alternatives. Every sentence adds value, though it could be slightly more structured (e.g., bullet points) for easier scanning.

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?

Given the complexity (paid tool, multiple outputs, errors, authentication), the description covers all essential context: return values, complementary tools, error types, pricing, and authentication requirements. An output schema exists but the description still concisely explains what to expect.

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 input schema has 100% description coverage for the sole parameter 'github_url'. The description does not add any additional meaning or format details beyond what the schema provides, so baseline score of 3 is appropriate.

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 states the tool's function: 'Analyze a GitHub repository and generate 99 structured AXIS artifacts across 19 programs.' It specifies the action (Analyze), the resource (GitHub repository), and the output (artifacts). It also differentiates from siblings like analyze_files and list_programs.

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?

Explicitly tells when to use: 'Use this when the source of truth is a GitHub repo URL.' Provides alternatives: 'Use analyze_files instead for inline file payloads or list_programs/search_and_discover_tools when you are still selecting a workflow.' Also mentions private repo requirements and pricing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate non-destructive and non-read-only behavior. The description adds context about the input state (70-80% complete) and output (packaging artifacts), but does not fully detail side effects like file creation or modification. Still more informative than relying solely on annotations.

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?

The description is a single sentence that packs the core purpose and outcome without unnecessary words.

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?

Given the tool's complexity (multi-marketplace packaging), the description mentions key aspects like input state and output artifacts. The presence of output schema accounts for return values. Lacks explicit prerequisites or examples, but is largely complete.

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?

Schema coverage is 100%, so baseline is 3. The description adds no extra meaning beyond what the schema already provides for the five optional parameters.

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 states the tool takes a 70-80% complete project directory and generates packaging and certification artifacts, distinguishing it from sibling tools which focus on analysis and discovery.

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 implies usage when a project is nearly complete and needs to be shipped, but lacks explicit guidance on when not to use it or alternatives. No direct siblings exist, so it is adequate but minimal.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. The description adds that it is free, requires no auth, and logs lightweight task metadata for intent analytics, which are valuable behavioral disclosures beyond annotations.

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?

The description is concise with four sentences covering purpose, cost/auth, logging, example usage, and sibling differentiation. Every sentence adds value, and key information is front-loaded.

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?

Given the tool has a simple input schema with all optional parameters, an output schema (so return values need not be described), and safety annotations, the description sufficiently covers purpose, usage, behavioral context, and differentiation from siblings, making it complete.

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?

Schema description coverage is 100%, so baseline is 3. The description does not add extra meaning to parameters beyond what is in the schema, which is acceptable given the schema's completeness.

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 states the tool discovers the best AXIS workflow for purchasing or compliance tasks, and distinguishes it from search_and_discover_tools by specifying commerce-specific triage. This provides a specific verb and resource with sibling differentiation.

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?

Explicitly says 'Use this when you need commerce-specific triage and next-step guidance' and 'Use search_and_discover_tools instead for non-commerce keyword routing across all programs,' giving clear when-to-use and alternative guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds valuable behavioral context beyond annotations: it explicitly states 'Free, no auth, and no mutation beyond read access', which clarifies cost, authentication, and safety aspects. While annotations already indicate readOnlyHint=true and destructiveHint=false, the description reinforces this with plain language and adds practical constraints.

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?

The description is efficiently structured: first sentence states purpose, second adds behavioral traits, third gives concrete example, fourth provides usage guidelines, and fifth distinguishes from alternatives. Every sentence earns its place with no wasted words.

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?

Given the tool has no parameters, comprehensive annotations, and an output schema exists, the description provides complete context. It covers purpose, behavioral traits, usage scenarios, and sibling differentiation, making it fully adequate for agent understanding.

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?

With 0 parameters and 100% schema description coverage, the baseline would be 4. The description doesn't need to explain parameters, but it provides context about what the tool discovers (metadata, pricing, manifests) which helps understand the output semantics.

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 states the tool's purpose with specific verbs ('discover AXIS install metadata, pricing, and shareable manifests') and resources ('commerce-capable agents'). It explicitly distinguishes from siblings by naming alternatives ('search_and_discover_tools' and 'discover_agentic_purchasing_needs') for different use cases.

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 provides explicit guidance on when to use this tool ('call before wiring AXIS into Claude Desktop, Cursor, or VS Code', 'when you need onboarding and ecosystem setup details') and when to use alternatives ('Use search_and_discover_tools instead for keyword routing or discover_agentic_purchasing_needs for purchasing-task triage').

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context by listing possible errors (snapshot-not-found, invalid-path, artifact-not-found) and stating access requirements ('Requires access to the snapshot'). No contradictions with annotations.

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?

The description is three sentences with no wasted words. It front-loads the main purpose, then covers errors, an example, and usage guidance in a logical order.

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?

The tool has an output schema (not shown but noted in context), so return value explanation is not needed. The description covers purpose, usage, errors, and an example, making it complete for a read-only tool with clear annotations.

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?

Both parameters have descriptions in the input schema (100% coverage). The description adds an example ('snapshot_id=abc-123, path=AGENTS.md'), which clarifies the format and combination of parameters beyond the schema.

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 explicitly states 'Read one generated artifact by snapshot_id and path,' providing a specific verb and resource. It distinguishes from the sibling tool 'get_snapshot' by noting that this tool retrieves a single artifact while the sibling gets the artifact list.

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 clearly specifies when to use this tool: 'Use this when you need the full text of one artifact. Use get_snapshot instead when you first need the artifact list.' This provides explicit guidance and an alternative.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already provide idempotentHint=true and destructiveHint=false. Description adds context: 'has no usage charge' and 'may persist a new referral code if one does not exist yet', explaining the possible side effect. No contradictions.

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?

Five concise sentences covering purpose, requirements, example, and usage guidance. Every sentence provides value; no redundancy.

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?

Given low complexity (0 params, simple get/create operation) and presence of output schema, the description fully covers purpose, behavior, and usage context.

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 tool has 0 parameters with 100% schema coverage, so the baseline is 4. Description adds no parameter info, but none is needed.

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 states 'Get or create the caller's AXIS referral token' – a specific verb and resource. It distinguishes from sibling tool get_referral_credits by specifying using this for the shareable token vs balances/milestones.

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?

Explicitly states when to use this tool ('when you need the shareable token itself') and the alternative ('Use get_referral_credits instead when you need balances...'). Also mentions required authentication: 'Requires Authorization: Bearer <api_key>'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds valuable behavioral context beyond annotations: it specifies authorization requirements ('Requires Authorization: Bearer <api_key>'), indicates no usage charge, clarifies that it returns a 'current discount ledger without creating a new analysis', and provides an example use case. While annotations cover read-only and idempotent aspects, the description enhances understanding with practical details, though it doesn't mention rate limits or error handling.

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?

The description is well-structured and front-loaded with key information: purpose, authorization, cost, and return value. Each sentence adds value, such as the example and sibling differentiation, with no wasted words. It efficiently communicates necessary details in a compact form.

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?

Given the tool has 0 parameters, rich annotations (readOnlyHint, idempotentHint), and an output schema, the description is complete. It covers purpose, usage guidelines, authorization, cost, behavioral traits, and sibling differentiation, providing all needed context without needing to explain return values due to the output schema.

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?

With 0 parameters and 100% schema description coverage, the baseline is 4. The description appropriately does not discuss parameters, as none exist, and instead focuses on the tool's purpose and usage, which is efficient and avoids redundancy.

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 states the specific action ('Get') and the resource ('caller's referral earnings, milestones, and free-call status'), distinguishing it from the sibling tool get_referral_code which is for shareable tokens. It provides a concrete example of when to use it, making the purpose unambiguous and well-differentiated.

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 explicitly states when to use this tool ('Use this when you need balances and milestones') and when to use an alternative ('Use get_referral_code instead when you only need the shareable token'). It also provides a contextual example ('call after a referral campaign to inspect earned credits'), offering clear guidance on usage scenarios.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description does not need to cover safety. It adds value by explaining the tool returns both status and artifact listing, that snapshots persist, and that they can be shared. This provides behavioral context beyond what annotations alone offer, without any contradiction.

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?

The description is three sentences, each carrying essential information: purpose, usage guidance, and persistence benefit. There is no extraneous text, and the information is front-loaded, making it highly concise and well-structured.

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?

Given the tool has a single parameter, clear annotations, and an output schema present, the description provides all necessary context: what it does, when to use it, and why snapshots are valuable. The output schema handles return format details, so the description is complete without needing to elaborate further.

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 input schema has 100% coverage with a clear description for snapshot_id. The description adds only that snapshot_id comes from analyze_repo or analyze_files, which reinforces but does not significantly extend beyond the schema's explanation. With high schema coverage, a baseline of 3 is appropriate.

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 states the tool retrieves 'status and the full artifact listing for a prior analysis by snapshot_id'. It uses a specific verb (Retrieve) and resource (snapshot), which distinguishes it from sibling analysis tools like analyze_repo and analyze_files, as well as get_artifact which likely returns a single artifact.

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 explicitly tells when to use this tool: 'to re-enumerate artifact paths without re-running analysis' and mentions sharing to avoid duplicate costs. While it does not include explicit when-not-to-use statements, the context and sibling tools make the alternatives clear, and the guidance is actionable.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate idempotentHint=true and destructiveHint=false, and the description confirms it is a read operation ('scrape'). It adds transparency about authorization ('Requires Authorization: Bearer <api_key>') and pricing. However, it does not detail error handling or rate limits, missing some behavioral context.

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?

The description is three sentences, each adding distinct value: purpose, use cases, and alternatives with authorization/pricing. It is front-loaded and concise with no wasted words.

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?

Given the complexity (2 params, output schema exists, good annotations), the description covers purpose, usage, auth, pricing, and alternatives. It is almost complete but could mention potential errors or rate limits for full contextual completeness.

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 input schema has 100% description coverage for parameters, so baseline is 3. The description mentions the return format ('markdown body, extracted metadata, and title') but does not explicitly clarify the 'only_main_content' parameter's effect—it implies full extraction while the default is to extract only main content, causing a slight inconsistency.

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 states it scrapes a single URL and returns markdown-formatted content, metadata, and title. It explicitly distinguishes itself from the sibling tool 'iliad_web_research_crawl' by noting that the sibling is for crawling multiple pages or following links.

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 provides explicit usage scenarios: 'Best for research, documentation reading, or SEO analysis.' It also names the alternative tool for different use cases ('Use iliad_web_research_crawl for crawling multiple pages or link following'), making it clear when to choose this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Adds important behavioral context beyond annotations: requires Authorization header, mentions pricing per crawl, and that up to 100 pages are covered. Annotations already provide idempotentHint=true and destructiveHint=false, but description enriches with auth and cost details.

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 focused sentences plus a final recommendation sentence. No redundancy, front-loaded with the core action and return type. Every sentence provides value.

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?

The tool is simple with only two parameters and an output schema. Description covers return type, auth, pricing, and usage context. Annotations provide idempotent and destructive hints. No missing critical information.

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?

Schema coverage is 100% with clear descriptions for both url and limit. The description does not add significant new meaning to the parameters beyond that, though it does reference 'covers up to 100 pages' which relates to the limit parameter.

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 states 'Crawl a domain and scrape multiple pages using Firecrawl' and lists use cases, also distinguishes from the sibling tool 'iliad_web_research' which is for single-page scrapes.

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?

Explicitly recommends 'Use iliad_web_research for single-page scrapes' and suggests best use cases (site mapping, content audits, bulk research), but does not provide explicit exclusion scenarios.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description goes beyond annotations by stating that the tool 'creates a snapshot' (indicating a side effect) and may return specific errors (auth, quota, file-limit, validation). Annotations already mark readOnlyHint=false, so this adds useful behavioral context without contradiction.

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?

The description is efficient: two sentences plus an example and a comparison. Every part is valuable, front-loaded with purpose and key constraints, and no wasted words.

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?

Given the presence of an output schema, the description does not need to explain return values. It covers purpose, usage guidance, authorization, errors, and alternative tool, making it fully complete for the tool's complexity.

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?

Schema coverage is 100%, so baseline is 3. The description provides an example ('pass your agent source files to see missing AGENTS.md, CLAUDE.md, and MCP config gaps') that adds contextual meaning to the parameters, earning an extra point.

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 states the tool analyzes an agent codebase and returns a prioritized AXIS hardening plan. It distinguishes itself from the sibling analyze_files by specifying that this tool provides recommendations and missing-context detection, while analyze_files returns the full artifact bundle directly.

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 explicitly says 'Use this when you want recommendations and missing-context detection. Use analyze_files instead when you want the full artifact bundle directly.' It also mentions required authorization and potential errors, providing clear guidance on when to use this tool versus its sibling.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover readOnly, idempotent, non-destructive. Description adds 'Free, no auth, and no side effects' and 'Inventory mode,' providing complementary context without contradiction.

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, front-loaded with purpose and output details, followed by usage guidance. No redundant or extraneous text.

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?

Output schema exists, so description doesn't need to detail return values. Description fully covers the tool's purpose, scope, and relation to siblings.

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?

No parameters, so baseline 4 applies. Schema coverage is 100%. Description adds no parameter info, but none needed.

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?

Description clearly states it lists all 19 AXIS programs and specifies the included fields (generators, pricing tier, artifact paths). It distinguishes from siblings by name-dropping alternative tools for different use cases.

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?

Explicitly tells when to use search_and_discover_tools (keyword) and discover_commerce_tools (install/onboarding metadata), plus states free/no auth/no side effects for broad applicability.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds valuable behavioral context beyond annotations: it mentions authorization requirements ('Requires Authorization: Bearer <api_key>'), potential errors ('may return auth, quota, payment, file-limit, or validation errors'), and that paid analysis records a new snapshot. Annotations cover basic safety (readOnlyHint=false, destructiveHint=false), but the description provides operational details that help the agent understand execution implications.

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?

The description is appropriately sized and front-loaded with the core purpose. Each sentence adds value: purpose, requirements/errors, example, usage guidelines. While slightly dense, there's minimal waste - every clause serves to clarify tool behavior or usage.

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?

Given the tool's complexity (11 parameters, mutation capability), rich annotations, and the presence of an output schema, the description provides excellent contextual completeness. It covers purpose, authorization, error conditions, usage guidelines, and distinguishes from alternatives - addressing what the structured fields don't explicitly convey about operational context.

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?

With 100% schema description coverage, the schema already documents all 11 parameters thoroughly. The description adds minimal parameter semantics beyond the schema - it only mentions 'focus_areas' in the example and implies 'files' usage. This meets the baseline expectation when schema coverage is complete.

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 states the tool's purpose with specific verbs ('prepare a codebase for agentic purchasing') and resources ('return a readiness score plus commerce artifacts'). It explicitly distinguishes from sibling 'discover_agentic_purchasing_needs' by stating when to use each tool, making the purpose highly specific and differentiated.

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 provides explicit guidance on when to use this tool ('when you need AP2/UCP/Visa, CE 3.0 dispute evidence, checkout, dispute, and negotiation hardening') and when to use an alternative ('Use discover_agentic_purchasing_needs instead when you only need workflow triage'). This gives clear context for selection among sibling tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent, non-destructive. Description adds 'Free, no auth, and no stateful side effects,' which is consistent and provides extra behavioral context. No contradiction.

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 plus a brief example and usage guidelines. Every sentence serves a purpose; front-loaded with core action and output. No extraneous information.

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?

With output schema present, description does not need return values. Covers purpose, usage context, behavioral traits, and sibling distinctions. Complete for a search tool given rich annotations and schema.

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?

Schema coverage is 100% with both parameters described. Description does not add meaning beyond what the schema provides; the example illustrates usage but not parameter details. Baseline 3 is appropriate.

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?

Description clearly states the tool searches programs by keyword, returns ranked matches with artifact paths, and includes an example. It explicitly distinguishes from siblings (list_programs, discover_commerce_tools, discover_agentic_purchasing_needs).

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?

Explicitly states when to use: 'when you know the outcome you want but not the right program.' Also lists specific alternatives for different scenarios, reducing confusion.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.