Bab Aljazair

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the tool is safe. The description adds a behavioral requirement: 'Preserve the research disclosure in any explanation.' This goes beyond the annotations by specifying how the output should be used in explanations. 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 two sentences and directly states the purpose and a behavioral note. It is concise, though the second sentence about 'research disclosure' may be unclear without context. No 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?

Given the presence of an output schema (not shown, but indicated), the description does not need to detail return values. It covers the core functionality and adds a behavioral instruction. It does not mention error scenarios, but for a simple read retrieval this is acceptable.

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 all parameters are described in the schema. The description adds no additional meaning beyond what the schema provides, such as formatting or usage details. 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 specifies the tool returns 'concise, office-aware checklist data for one consular procedure' and distinguishes it from siblings by noting 'without rendering a widget'. The verb 'return' and resource 'consular procedure checklist data' are specific.

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 phrase 'without rendering a widget' implies this tool is for data retrieval as opposed to UI display, but there is no explicit guidance on when to use this tool versus sibling tools like 'search_consular_procedures' or 'show_consular_dossier'. No alternatives or exclusions are mentioned.

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 doesn't need to reiterate safety. It adds useful context about what the tool returns (jurisdictions and official websites) beyond the structured fields.

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 two concise sentences. The first front-loads the core purpose, and the second adds a usage hint without redundancy. Every sentence earns its place.

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 simplicity (one optional parameter, no nesting), the description covers purpose and usage context adequately. An output schema exists (not shown) so return details need not be described. This definition is 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 description coverage is 100% and the single parameter 'language' is fully described in the schema (enum values and default). The description adds no additional meaning beyond the schema, so 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?

The description clearly states it lists all Algerian consular offices in France with jurisdictions and websites, using specific verb 'List' and resource 'consular offices'. It distinguishes from sibling tools like locate_consular_office (single office) and search_consular_procedures (procedures).

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 includes 'Use when the user wants the network or needs to choose manually' which provides some context but does not explicitly state when not to use it or compare to alternatives like search_consular_procedures. It gives implied usage without exclusions.

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 indicate a safe read operation (readOnlyHint=true, destructiveHint=false). The description adds context about input flexibility but does not disclose rate limits, authorization requirements, or edge cases like what happens if no matching office is found.

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 wasted words. The first sentence states the core purpose, the second lists the input types. Efficient and 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?

The tool has an output schema (not shown), so return values are presumably covered. The description covers purpose and inputs adequately. Minor gap: no mention of behavior for invalid input or cases where input maps to multiple offices.

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% and already explains both parameters. The description only restates the accepted input types, adding no new semantic value beyond what the schema already provides.

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 action ('Resolve') and the resource ('Algerian consular office responsible for a residence'). It specifies the geographic scope (France) and acceptable inputs, but does not explicitly distinguish it from sibling tools like 'list_consular_offices'.

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 when to use the tool (when you need to find which consular office handles a given residence), but provides no explicit guidance on when not to use it or mention of alternatives among the 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 readOnlyHint=true and destructiveHint=false, covering key behavioral traits. The description adds that including an office 'exposes the research level', which provides some additional but vague context. No contradiction is present.

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 at two sentences, but the second sentence ('Optionally include an office to expose the research level') is somewhat unclear and could be improved for clarity. Overall, it is front-loaded and to the point.

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?

Despite having an output schema, the description does not explain what the search returns (e.g., procedure IDs, full details). While the schema covers some parameters, the overall explanation of the tool's behavior is incomplete given the 5 parameters and low schema coverage. The phrase 'research level' is ambiguous.

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 only 20%, so the description should compensate. It clarifies that 'officeId' relates to 'research level' and implies 'query' from the natural-language intent. However, it does not explain 'limit', 'theme', or the purpose of 'language' beyond what the schema already provides (the schema has a description for 'language'). Thus, parameter semantics are insufficient.

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 searches the Bab Aljazair catalogue of consular procedures and resolves procedure IDs from natural language. It distinguishes from siblings (e.g., 'get_consular_procedure' which retrieves a specific procedure, 'list_consular_offices' which lists offices) by focusing on search and resolution.

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?

Explicit guidance to use the tool when needing to resolve procedure IDs from natural-language intent is given. The mention of optionally including an office provides context. However, it does not explicitly state when not to use it (e.g., if a procedure ID is already known, use get_consular_procedure instead), but the sibling list implies alternatives.

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; description adds 'Render' which implies no mutation. No additional behavioral context is provided beyond what annotations offer.

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 usage, no wasted words. Efficient and clear.

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?

Adequate given the presence of output schema and fully described parameters. It covers the tool's purpose, when to use, and basic behavior, but could briefly mention the interactive nature.

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%; all parameters have clear descriptions in the schema. The description does not add extra meaning to parameters beyond stating that office and procedure IDs must be 'resolved'.

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 uses specific verb 'Render' and noun 'interactive... dossier checklist', and distinguishes from sibling tools like get_consular_procedure or list_consular_offices by focusing on displaying a personalized checklist for a known office and procedure.

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?

States 'Use once the office and procedure IDs are known' and 'especially when the user wants to prepare, personalize, or track the dossier', providing clear context. However, it does not explicitly mention when not to use or direct to alternatives.

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