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

Annotations already mark the tool as destructive and non-idempotent, so the description wisely adds context: it interrupts mid-execution and cascades to active sub-agents via root_execution_id in multi-agent scenarios. It does not detail consequences like partial output handling, but the key behavioral traits are disclosed and consistent with the 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?

Three dense sentences each carry meaningful content: the core action, the applicable scenarios, the distinction from a sibling tool, and the multi-agent cascading behavior. No filler or repetition; the most important 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?

The description is largely complete for a destructive cancellation tool: it names the target, the problem cases, the alternative, and the multi-agent propagation behavior. It could be slightly stronger on irreversibility or what happens to already-produced partial output, but overall an agent has enough to decide when and how to invoke it.

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 the schema already documents session_id and reason. The description adds no additional parameter-level meaning beyond what the schema provides, so the 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 states a precise verb and resource: it cancels an agent turn that is in progress (mid-LLM, mid-tool, mid-stream). It clearly distinguishes itself from the sibling tool set_session_control(suspended), making the tool's scope unmistakable.

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?

It explicitly states when to use this tool: when the agent is in an expensive loop, responding incorrectly, or the consumer asks to stop. It also contrasts with set_session_control(suspended), telling the agent exactly when this tool is the right choice instead of 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?

Goes well beyond the annotations (readOnly=false, openWorld=true, idempotent=false, destructive=false): it enumerates outcome values, explains that success is true only for COMPLETED/LENGTH, details TIMEOUT/TURN_TIMEOUT/timed_out/timeout_clock behavior, describes gated responses that skip agent execution, and documents session adoption/CONFLICT rules. Rich behavioral disclosure that the annotations cannot carry.

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?

Purpose is front-loaded in the first line, which is good, but the body is very long with multiple paragraphs, a capitalized IMPORTANTE block, and dense integration notes. Much of it earns its place given the tool's complexity, yet it could be tightened without loss.

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 8 parameters, nested objects, admin/owner-only fields, and no output schema, the description compensates fully by enumerating the response fields (response, session_id, tools_used, tool_calls, execution_time_ms, model_used, execution_id, outcome) and the gate/error cases. An agent has everything needed to call and interpret it.

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 already 100%, so the baseline is 3, but the description adds genuine meaning: that bindings are authoritative tool arguments never sent to the model or persisted, that context is read-only origin data never placed in the system prompt, that session_from mirrors webhook derive hashing, and the accepted_fields/ignored_fields return contract.

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?

First sentence gives a specific verb (envia mensagem) and resource (agente) plus a decisive scope qualifier: synchronous, no progressive streaming. This immediately distinguishes it from asynchronous/messaging siblings like send_manual_message or cancel_agent_turn.

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?

Provides clear operational context: use session_id on subsequent calls to keep conversation context, or use session_from in integrations so you don't have to store an id, and warns not to combine the two. It doesn't explicitly contrast with the closest sibling (send_manual_message) or state when-not-to-use, so it stops short of a 5.

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 discloses important side effects not visible in annotations: the clone is always created in draft status, triggers are cloned disabled by default, and invalid schemas only produce warnings without blocking. This is exactly the behavioral context an agent needs beyond the structured annotation hints.

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?

Three short, information-dense sentences with no filler. The main action and post-condition are front-loaded, and each subsequent sentence adds meaningful detail without repeating schema content.

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 description covers the essential post-conditions, optional trigger cloning, and non-blocking schema warnings. With no output schema, it does not describe the return value, but for a cloning operation the stated behavior is largely sufficient. A brief note on what the response contains would make it fully 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 the input schema already documents agent_id, new_name, include_schemas, and include_triggers with defaults. The description adds some behavioral nuance around invalid schemas and trigger state, but it does not substantially expand on the parameter semantics already present in 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 begins with a specific verb and resource: 'Clona um agente existente' and immediately tells the agent the resulting state ('criado em status draft'). This clearly distinguishes clone_agent from create_agent and other agent-management siblings.

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 clear context for when the tool is appropriate: duplicating an existing agent along with its schemas. It also clarifies optional trigger cloning. It does not explicitly name alternatives or exclusions, but the use case is obvious enough to guide selection.

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 provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the field-by-field diff behavior, which is consistent with annotations, but it does not disclose behavior for invalid versions or how the diff is structured.

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?

A single sentence packs the action, resource, and result type with no filler. It is appropriately front-loaded and easy to parse.

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 read-only comparison tool with fully documented parameters and safety annotations, the description covers the core behavior and return style. It does not specify output structure or invalid-version handling, but these are not heavily needed given the low complexity and the presence of 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?

Schema description coverage is 100%, so each parameter already has clear meaning: resource_type is an enum, resource_id is a UUID, and version fields specify older/newer. The description adds no parameter-level detail beyond this, so the baseline of 3 applies.

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 states a clear verb ('Compara') and resource ('duas versões de um recurso'), and specifies the output ('diff campo a campo'). This distinguishes it from siblings like get_version (single version retrieval) and list_versions (all versions listing).

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 name and description imply use when comparing two versions, but there is no explicit statement of when to choose this tool over get_version or list_versions. No alternatives, exclusions, or preconditions 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 signal that this is not read-only (readOnlyHint=false), so the mutation nature is covered. The description adds one behavioral detail beyond annotations: it returns the created agent object with its UUID. However, it does not disclose side effects, required permissions, failure modes, or idempotency expectations beyond what annotations imply.

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 short, front-loaded sentences with zero redundant wording. It states the action first and the return contract second, making it easy for an agent to parse quickly.

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 rich schema descriptions and the annotation set, the description provides the essential missing piece: the return contract (created agent with UUID). It does not explicitly cover when to prefer this over cloning or publishing, and there is no output schema, but the tool is a straightforward create operation and the current description plus schema is largely sufficient for invocation.

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% parameter description coverage, including examples for llm_config and model patterns, so the baseline is 3. The description adds no parameter-level information, but the schema already carries the full semantic burden for all 8 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 uses a specific verb and resource: 'Cria um novo agente' (creates a new agent). It also adds the return value behavior ('Retorna o agente criado com seu UUID'), which distinguishes it from sibling tools like update_agent, delete_agent, and list_agents. The action is unambiguous.

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 no guidance on when to use this tool versus alternatives such as clone_agent, publish_agent, or update_agent. There are no stated conditions, prerequisites, or exclusions. The only usage signal is the tool name itself, which is implicit rather than explicit.

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 substantial behavioral context beyond the annotations: the generated key is displayed only once, prefixes are semantically equivalent, roles have anti-escalation rules, 'owner' is unavailable for API keys, and omitted rate_limit_per_minute defaults to the tenant plan maximum. This is valuable operational information that the sparse annotations do not convey.

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 with front-loaded purpose and security-critical warnings. Every sentence contributes operational knowledge, from the one-time display warning to prefix semantics, role restrictions, and rate-limiting defaults. There is no filler or redundant restating of the input schema.

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 mutating tool with no output schema, this description covers return behavior, secret handling, role constraints, prefix semantics, and default rate-limit behavior. An agent has enough to invoke the tool correctly and to know what to expect, including the critical 'save immediately' warning. No essential call-time information is missing.

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 the baseline is 3, but the description adds meaningful semantics: default behavior when rate_limit_per_minute is omitted, anti-escalation constraints on role, role capability details, and the note that 'owner' is not a valid API key role. This goes beyond the schema descriptions without needing to repeat every 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 opens with 'Cria uma nova API Key para o tenant', which is a specific verb plus resource. It also says the full key is returned and visible only once, immediately making the tool's purpose distinct from sibling tools like list_api_keys, get_api_key, update_api_key, and delete_api_key.

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 'Cria uma nova API Key' clearly signals when to use this tool, and sibling names make the alternatives for listing, retrieving, updating, and deleting unambiguous. It does not explicitly say 'use update_api_key to modify' or 'use list_api_keys to view', but the context is clear and no exclusions are needed.

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 the all-false annotations, the description discloses that the server injects tenant_id and created_by, and clarifies that creation alone does not activate the policy—binding to an agent's CSP is required. This is meaningful behavioral context for a write operation.

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?

Three dense sentences front-load the purpose, then give the approver shapes, activation path, and contract constraints without repetition. Every sentence adds needed 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?

For a creation tool with no output schema, the description covers the call contract, parameter restrictions, and the post-creation activation requirement. It does not describe the response shape or error cases, but those are not essential for a correct first invocation.

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 the baseline is 3; the description adds examples for approvers ({type:'user', id:'<uuid>'} vs {type:'role', role:'admin'}) and restricts the payload to name/description/stages. This helps an agent construct valid input beyond the schema's enum/type descriptions.

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 opens with 'Cria uma política de aprovação', giving a specific verb and resource, and clarifies the domain (who approves tool actions under HITL). It is immediately distinguishable from sibling tools like list_approval_policies, get_approval_policy, and update_approval_policy.

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 primary use case (creating an approval policy) is clear, and the description adds an important follow-up step: the policy only takes effect when bound via CSP behavior.approval_policy_id + behavior.require_approval_for. However, it does not explicitly contrast this with update_approval_policy or state when not to use this tool, so alternative selection guidance is only implicit.

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 only cover the safety profile (readOnly=false, destructive=false, idempotent=false), and the description adds substantial behavioral context beyond that: unknown fields are silently accepted and left inert, tenant_id is server-injected, origin rules are stored but never enforced, and must_not_tools is filtered pre-turn including HITL resume. This is exactly the extra operational knowledge an agent needs.

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?

Front-loaded with the core purpose, then organized under clear headings (Escopos, Tipos, per-type examples, surface control, warnings, approval). It is long, and the two repeated ⚠️ warnings plus overlapping origin/must_not_tools notes are somewhat verbose, but nearly every block carries non-redundant 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?

For a nested-object, extra-properties-allowed tool with no output schema, the description supplies the contract reference, per-type rule examples, scope/heritage semantics, server-injected fields, and runtime-vs-stored caveats. An agent has everything needed to call it correctly without guessing field names.

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?

Even with 100% schema coverage, the description adds real meaning: concrete per-type rule shapes for schedule/behavior/data/custom, the pointer to zihin://schemas/csp_config and $defs.{tipo}Rules for authoritative field names, and the note that tenant_id is injected rather than passed. This goes well beyond the schema's generic descriptions.

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?

States a specific verb+resource ("Cria uma nova política de segurança contextual (CSP)") and immediately enumerates the scopes and policy types it supports. An agent can distinguish this from update_csp/get_csp/delete_csp/toggle_csp without opening any schema.

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 routes usage: enumerates when each policy_type applies (schedule/behavior/data/custom), and gives an explicit when-NOT-to-use warning that policy_type 'origin' is accepted but not enforced at runtime ("não use como controle de segurança"). It also points to the contract resource and the create_approval_policy sibling for approval policy IDs.

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 declare this is a non-readonly, non-idempotent create. The description goes well beyond that: it specifies per-call vs connection timeout semantics, that timeout retry is opt-in, the default 30s call timeout, and that tunnel tokens are resolved via env var rather than vault. No annotation 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?

Front-loaded purpose followed by a well-organized transport line and an auth_method/ config mapping list. Dense but every section earns its place; the parenthetical provenance notes ('doc loop-review/34 F1') add slight noise.

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?

Covers transports, all five auth methods with config shapes, and key optional fields for a 7-param creation tool with no output schema. Missing only a note about required error cases (e.g., duplicate names) or the return value, which is minor.

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, but the description adds real meaning beyond the schema: the exact config shapes per auth_method (bearer vs api_key vs oauth with required keys), the allowed timeout ranges, and the contract reference 'zihin://schemas/mcp_resource_config'.

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?

States a specific verb+resource (register a new MCP server for an agent) and adds the consequence ('the agent can then use the tools exposed by the server'). Distinguishes clearly from siblings like update_mcp_server and test_mcp_server.

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?

Provides rich guidance on transport selection (http vs stdio, sse deprecated) and when to use each auth_method (tunnel for Zihin Tunnel, oauth for client credentials). Lacks explicit when-not-to-use framing or routing to update_mcp_server for existing servers, but context is strong.

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 non-readonly, non-idempotent, non-destructive, closed-world. The description adds real behavioral context beyond that: the cross-field enforcement rule (endpoint.name must equal tool_definition.name or the tool fails routing), that the server validates against a formal JSON Schema resource, and server-side enforcement of locked_fields. It does not discuss reversibility or auth requirements for the call itself, so it falls short of a 5.

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?

Front-loaded with purpose and type breakdown, which is good, but the text is very long and contains redundancy (the zihin://schemas/{schema_type} contract is stated twice) and internal jargon ('doc loop-review/34 F1') that gives an agent no usable signal. Much of the content earns its place given tool complexity, but the noise costs it.

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, nested-object, multi-type creation tool with no output schema, the description covers every variant, the critical API_CONFIG contract rules, transformation options, and a validation-first workflow. An agent has everything needed to construct a valid call without consulting external docs.

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 the baseline is 3. The description adds meaning the schema does not: it warns that the top-level 'name' param is legacy with no effect, and documents the internal structure semantics of schema_data per type (required minLengths, transformation fields, defaults_from_context behavior). This is genuine added value over 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?

States a specific verb+resource ('Cria um novo schema para um agente') and enumerates the six schema_type values the tool accepts. It also explicitly distinguishes itself from siblings by declaring 'Triggers e CSPs NÃO são schemas: use create_trigger e create_csp,' so an agent can route correctly without opening other schemas.

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?

Gives an explicit when-to-use workflow ('leia o resource zihin://schemas/{schema_type}, monte o schema_data, valide com validate_schema_data (dry-run), então crie') and names the sibling tools that handle non-schema cases (create_trigger, create_csp). It even points to create_csp for multi-agent fields, leaving little to inference.

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?

Discloses important behavior beyond annotations: encryption via AES-256-GCM, storage in the vault, and especially that the plaintext value will not be returned after creation and must be saved beforehand. This is critical operational context that readOnlyHint, idempotentHint, and related annotations do not provide.

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?

Three short, focused blocks: the action, a critical warning, and downstream usage guidance. Every sentence earns its place, and the most decision-relevant facts are 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?

For a creation tool with full schema coverage and no output schema, the description supplies sufficient context: what is created, how it is protected, what the agent must retain, and how to use the result. The warning about plaintext not being returned is especially valuable given the absence of an 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?

The input schema already provides 100% parameter coverage with descriptions and examples. The description adds genuine value by explaining that the 'name' parameter becomes secret_ref in api_config auth or vault_secret_id in connection_config, which is not stated in the schema. It does not add detail for category or usage_hint, but their schema descriptions are already sufficient.

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?

States 'Cria um novo secret criptografado para o tenant' — a specific verb (create), resource (secret), and scope (tenant). The 'novo' distinguishes it from update/delete/list secret siblings, making the creation operation unambiguous.

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?

'Cria um novo secret' frames when to use the tool: when a new secret is needed. The downstream note 'use o name como secret_ref em api_config auth...' reinforces the practical use case. It does not explicitly name alternatives like update_secret or delete_secret, but the create/update/delete sibling cluster makes the distinction clear.

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 the annotations (readOnly=false, destructive=false, idempotent=false), the description discloses genuinely behavioral facts: server-side injection of tenant_id and ids, the authoritative validation contract at zihin://schemas/trigger_config, the default transforms derived from response_adapter.format, and that memory_config is rejected by the server for schedule triggers. This is exactly the extra context the annotations cannot carry.

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 purpose and validation contract are front-loaded, but the body is very long and largely duplicates the trigger_config JSON Schema already present in the input schema, including enum lists and defaults. It is dense and mostly single-paragraph, so structure could be improved and a good deal of the config recitation is redundant.

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, three-variant, nested-config creation tool with no output schema, the description covers type-dependent structures, enum restrictions, server-side injections, rejected fields, and default transformations. An agent has enough to call it correctly without further inference.

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 the baseline is 3, but the description adds semantics the schema does not: sender_access controls who can invoke the webhook ('any'/'members'/'whitelist'), message_buffer groups rapid messages via Redis debounce, and split_config chunks long responses for size-limited channels. It meaningfully enriches several nested parameters rather than merely restating them.

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 opening sentence 'Cria um novo trigger para um agente' states a specific verb and resource, and the rest of the text makes the creation semantics unambiguous. However, it never explicitly distinguishes itself from siblings like update_trigger, get_trigger, or test_trigger, so it falls short of a 5.

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 imposes real invocation constraints ('Use SOMENTE os enums abaixo', don't invent values, send only agent_id/name/trigger_type/trigger_config since tenant_id and ids are server-injected), which is useful guidance. It gives no explicit criteria for when to choose create_trigger over update_trigger or test_trigger, so it remains implied rather than explicit.

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 signal mutation and destructiveness, and the description adds the valuable nuance that the delete is soft and reversible ('soft delete', 'pode ser restaurado depois'). It does not detail effects on related resources or whether deletion is idempotent, but the core behavior is disclosed beyond the annotated flags.

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 short sentences carry the operation, its soft-delete nature, and reversibility with no filler. Every sentence adds information, and the key action 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?

For a one-parameter, schema-covered operation with no output schema, the description covers the essential safety-relevant detail: it is reversible. It could mention what happens to the archived agent's active sessions or visibility, but nothing critical is missing for a simple soft-delete call.

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 sole parameter is fully documented in the schema ('UUID do agente a arquivar'), so the description does not need to provide parameter meaning. The description adds no extra semantic detail about the parameter beyond the schema, matching the baseline for high schema coverage.

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 uses a specific verb ('Arquiva') and resource ('um agente'), and immediately clarifies that this is a soft delete, distinguishing it from a destructive removal. The added note that the agent can be restored later sharpens the meaning of the operation.

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 restorability note implies this tool is the choice when an agent must be removed but kept recoverable, which is a usable usage cue. However, the description does not name alternative tools or state when not to use it, leaving the when-to-use guidance mostly implicit.

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 destructiveHint=true and idempotentHint=false, but the description adds genuinely new behavioral context: it is a SOFT delete (memory recoverable, not permanently purged) and platform-controlled keys are protected. These details go beyond the structured 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?

Compact and front-loaded, leading with the action and soft-delete nature, then the required inputs, then the constraint. Every sentence carries information, though the required-parameter sentence is slightly redundant with the schema.

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 destructive delete with annotations already covering the safety profile and no output schema, the description supplies the key extras (soft delete, protected keys). It omits any mention of the scope parameter's effect, but that is documented in the 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 description coverage is 100%, so the schema already documents all four parameters including the scope enum. The description only restates the three required parameter names, adding no syntax or semantic value beyond the schema; baseline 3 applies.

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?

States a specific verb and resource ('Remove (soft delete) uma memória específica de um agente'), which is precise and unambiguous. It does not explicitly differentiate itself from the sibling list_agent_memory, so it falls short of a 5.

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?

Provides one useful constraint ('Chaves com prefixo "_" são controle da plataforma e não podem ser removidas por aqui'), which tells the agent when the call will fail. However, there is no guidance on when to use this versus alternatives like list_agent_memory, nor prerequisites about scope selection.

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 destructiveHint=true, readOnlyHint=false, and idempotentHint=false. The description adds value beyond these by disclosing that revocation is permanent and that dependent triggers and webhooks will stop functioning. This is useful behavioral context not present in the 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 short, front-loaded sentences. The first states the core action and permanence; the second adds the most important side effect. No filler or 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?

For a simple single-parameter destructive tool with annotations already covering the safety profile, the description is largely complete: it states permanence, the side effect on triggers/webhooks, and the schema covers the parameter. It lacks an explicit pointer to non-destructive alternatives or reversibility, but these are minor gaps given the tool's simplicity.

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 sole parameter key_id has a full description in the schema ('UUID da API Key a revogar'). The tool description adds no additional parameter-level meaning, so the baseline 3 applies.

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 states a specific verb ('Revoga' = revokes), a clear resource ('uma API Key'), and adds the modifier 'permanentemente' to distinguish permanent revocation from other operations. This clearly differentiates it from sibling tools like update_api_key, which modify rather than permanently revoke.

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 makes the usage context clear: use this when you want to permanently revoke an API key, and it warns about the consequence that triggers and webhooks using the key will stop working. It does not explicitly name an alternative like update_api_key for non-destructive changes, so it stops short of a full when/when-not comparison.

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 destructiveHint=true and readOnlyHint=false, so the destructive nature is known. The description adds the 'permanentemente' qualifier, signaling irreversibility, but does not mention cascading effects, required permissions, or failure behavior if the CSP is in use.

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 one short, direct sentence with no filler or repeated schema information. The key message—permanent removal of a security policy—is front-loaded and easy to parse.

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 one-parameter delete operation with destructiveHint and idempotentHint annotations, the description sufficiently states the action and permanence for invocation. It omits post-deletion effects and return value, but no output schema exists and the operation is simple.

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%; the single required csp_id parameter has a UUID format and a description ('UUID da CSP a remover'). The tool description adds no parameter-level detail, but the schema fully documents the parameter, so the baseline of 3 applies.

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 uses a specific verb ('Remove') and resource ('uma política de segurança') and adds 'permanentemente', making it clear this is a permanent deletion tool. This distinguishes it from sibling tools like create_csp, update_csp, toggle_csp, and list_csps even without naming them.

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 no guidance on when to use this tool versus alternatives. It does not contrast permanent deletion with toggle_csp for temporary disabling or update_csp for modification, leaving the agent to infer usage context.

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 destructiveHint=true readOnlyHint=false. The description adds a concrete behavioral consequence—'As tools do server deixam de estar disponíveis'—which is useful for an agent to understand the operational impact beyond the generic destructive flag. It does not contradict the 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 short sentences with no filler. The main action is stated first, and the consequence is given immediately after, making it easy for an agent to parse quickly.

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?

This is a straightforward single-parameter deletion tool. The description covers the core action and the immediate outcome, while the schema and destructiveHint cover the parameter and risk. Missing details such as irreversibility or authorization requirements are not explicitly stated, but given the low complexity and annotation coverage, the description is sufficiently 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%, and the parameter description ('UUID do MCP server a remover') already fully documents the only parameter. The tool description adds no additional meaning beyond what the schema already provides, 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 states a specific verb ('Remove') and a specific resource ('um MCP server de um agente'), clearly distinguishing this as the deletion operation among siblings like create_mcp_server, update_mcp_server, and test_mcp_server. It also adds the meaningful consequence that the server's tools become unavailable.

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: use this when you want to remove an MCP server from an agent, with the effect that its tools stop being available. However, it does not explicitly contrast it with alternatives such as update_mcp_server or invalidate_mcp_cache, nor does it state when not to use it. The guidance is implied rather than explicit.

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?

It discloses that this is a soft delete, that the schema becomes inactive, and that it can be reactivated—useful context beyond the destructiveHint annotation. It does not mention side effects on dependent resources or failure behavior, but annotations already cover the destructive nature, so the added reactivation detail is valuable.

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 short sentences with no filler. The primary action is front-loaded, and the soft-delete qualification immediately follows, making intent clear without 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?

For a single-parameter tool with a high-coverage schema and relevant annotations, this description is largely complete. It covers the key distinction from hard delete and the reactivation possibility, though it leaves minor gaps around what 'inactive' means operationally and how reactivation would be performed.

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 only parameter, schema_id, is fully documented in the schema as 'UUID do schema a desativar' with 100% coverage. The description adds no further semantic detail about the parameter, so the schema carries the load and the 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 deactivates a schema via soft delete, which prevents misinterpretation of the 'delete' name as a hard delete. It does not explicitly differentiate from the sibling 'toggle_schema', which may also affect schema active state, leaving some ambiguity about which operation is intended.

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 explains the effect but provides no guidance on when to use delete_schema versus alternatives such as toggle_schema or update_schema. There is no statement about when to prefer this tool or what scenarios call for the soft-delete behavior.

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 destructiveHint=true and readOnlyHint=false, but the description adds real value beyond them by disclosing the downstream consequence: api_configs referencing this secret will stop working. "Permanentemente" reinforces non-recoverability. It still omits that a non-existent name will error (idempotentHint=false) and whether auth/confirmation is required.

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 short sentences, zero filler, and the destructive consequence is front-loaded right after the action statement so the warning cannot be missed.

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 one-parameter destructive tool with no output schema and annotations covering the safety profile, the description supplies the one thing annotations cannot: the blast radius on referencing api_configs. Only the idempotency/error behavior of re-deleting is left unstated.

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?

There is a single parameter with 100% schema description coverage ("Nome do secret a remover"), so the schema fully documents it. The description adds no syntax, format, or lookup guidance beyond that, which is the expected baseline when the schema does the work.

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 verb+resource is explicit and specific ("Remove um secret permanentemente"), and "permanentemente" distinguishes it from the sibling update_secret. However, it never names update_secret or list_secrets as alternatives, so an agent must infer the routing from the verb alone.

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?

Usage is only implied: deleting versus updating a secret is inferable from the verb, but there is no statement of when deletion is appropriate, no prerequisites, and no pointer to update_secret for reversible changes. Minimum viable 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?

Annotations already mark the tool as destructive (destructiveHint: true). The description adds valuable context beyond that by explicitly stating the action cannot be undone, reinforcing the irreversibility for the agent. It does not address side effects or permissions, but for a single-parameter destructive action this is adequate.

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 short sentences with no filler. The key warning about permanence is front-loaded and immediately reinforces the destructive nature of the operation.

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 delete operation with one documented parameter and destructive annotations, the description is largely complete. It could mention the response/return behavior or cascading effects, but the provided information is sufficient for an agent to invoke the tool safely.

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 has 100% description coverage for the only parameter (trigger_id with a clear UUID description), so the description does not need to add parameter details. The tool description itself does not explain the parameter, but the schema already fully carries that responsibility.

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 ('Remove um trigger') and emphasizes permanence ('permanentemente', 'não pode ser desfeita'), making it distinct from update/toggle operations. It does not explicitly name sibling tools, but the resource and permanent-deletion semantics are unambiguous.

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?

No guidance is given on when to use this tool versus alternatives such as toggle_trigger for temporary deactivation. The irreversible nature is noted, but there is no explicit when-to-use or when-not-to-use framing.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds return-content context (schemas, triggers, configurations), but does not disclose operational behaviors such as error handling, permission requirements, or response structure beyond that.

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 front-loaded sentence with no filler. It immediately conveys the action and the key content categories, and every word contributes to understanding what the tool returns.

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 one-parameter read-only fetch, the description is mostly complete: it names the resource, the parameter is fully documented in the schema, and annotations cover safety. The main gap is the unresolved ambiguity with 'get_agent_full', which prevents full confidence in tool selection.

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%, and the single parameter 'agent_id' is already described as 'UUID do agente' in the input schema. The tool description adds no additional meaning, format details, or usage nuance for the parameter, so the baseline score applies.

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 states a clear verb ('Retorna') and resource ('detalhes completos de um agente'), and specifies what is included: schemas, triggers, and configurations. However, it does not differentiate this endpoint from the sibling 'get_agent_full', which appears to have an overlapping purpose.

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?

There is no guidance on when to use this tool versus alternatives such as 'list_agents' or 'get_agent_full'. The description implies it is for fetching details of a single agent, but it does not state exclusions, preconditions, or when a sibling would be more appropriate.

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, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds meaningful behavioral context: it counts ALL LLM calls including BYOK, and defines what unlimited=true means. These details go beyond annotations and clarify the semantics of the returned data.

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 zero wasted words. The main return values are front-loaded, and the technical detail about BYOK and unlimited is placed after the core message. 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?

For a getter with one parameter and no output schema, the description adequately states what is returned (budget and balance) and defines key terms (unlimited). It doesn't detail the exact JSON response structure, but with no output schema provided, this level of detail is acceptable. The behavioral context about BYOK rounding it out.

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% (agent_id is described as 'UUID do agente'). The description adds no new parameter semantics beyond what the schema provides. Baseline 3 applies because the schema fully documents the only 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 the specific verb 'Retorna' (returns) and the resource: the budget (spending cap in USD) and balance of the current cycle for a single agent. It indicates a read operation and implies it's for one agent via 'de um agente', but does not explicitly contrast with list_agent_budgets, which likely handles multiple agents.

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 for a single agent's budget but provides no explicit guidance on when to use this tool versus list_agent_budgets or other alternatives. It doesn't mention exclusions or scenarios. The context is clear but not directive, so a 3 is appropriate.

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, covering the safety profile. The description adds useful context about what the returned data includes, but it does not disclose response-size limits, authorization expectations, or behavior when some sections are empty or unavailable.

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 compact sentence that immediately states the tool's purpose and enumerates the included components. There is no filler, repetition, or unnecessary context.

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 read-only aggregate endpoint with one required parameter, the description covers the main expected return categories: data, schemas, triggers, CSPs, and publishing configuration. It stops short of full completeness because there is no output schema and no hint of response structure, such as nesting or whether some sections may be omitted.

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 has 100% description coverage and fully documents agent_id as 'UUID do agente'. The description does not add anything beyond the schema for the single parameter, which is acceptable given the complete schema coverage.

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 states a specific verb ('Retorna') and resource ('visão completa do agente'), and enumerates the exact contents: data, active schemas, triggers, linked CSPs, and publishing configuration. This differentiates it from more specific siblings like get_agent or list_triggers by establishing it as the aggregate 'full' view.

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 'visão completa' implies this tool is appropriate when the entire agent state is needed, which gives some contextual guidance. However, it does not explicitly mention when not to use it or name alternatives such as get_agent for basic agent data, so the differentiation from sibling tools is mostly left to inference.

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, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds meaningful behavioral detail: it filters to real invocations only, includes counts and last-use timestamps, and clarifies the semantic relationship to allowed_invoke_agents.

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 concise sentences fully convey the tool's purpose and differentiating context. The core action and result are front-loaded, and every sentence earns its place without unnecessary elaboration.

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 zero-parameter read-only tool, the description provides sufficient operational context: what is returned, the invocation filter, the counts, and the last-use timestamp. There is no output schema, but the described shape is simple enough. It could be slightly richer by mentioning ordering or scope, but the essentials are present.

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 zero parameters and the schema is empty, so the baseline is 4. The description adds no parameter details because none are needed; nothing about parameters is left unexplained.

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 states a specific verb and resource ('Retorna pares orquestrador→subagente'), defining that it returns actual invocations via invoke_agent, with invocation count and last use. It explicitly differentiates itself from allowed_invoke_agents, so an agent can distinguish its purpose clearly.

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 indicates this tool is for actual invocations, complementing allowed_invoke_agents (which expresses potential permission). This gives context on when to use it versus the conceptual alternative, though it does not explicitly name sibling tools or provide when-not-to-use conditions.

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, so the safety profile is covered. The description adds valuable behavioral details beyond those: SQL aggregation without row cap, tool-call metrics computed from a sample of the last 2000 calls with a sample_truncated flag, and specific latency percentiles. This goes beyond what annotations alone provide.

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 deliver dense, useful information with no filler. The first sentence front-loads what the tool returns, and the second provides use case and routing to an alternative. Every part 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?

With no output schema, the description carries the responsibility of explaining the return content, and it names the key metrics (calls, errors, success_rate, tokens, custo, latency p50/p95, sample_truncated, sessions). Minor details about the exact shape of the sessions portion are omitted, but the tool is callable and its results are sufficiently scoped.

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 both parameters already have clear descriptions: agent_id is a UUID and period has an enum with date ranges and defaults. The description does not add new parameter-level semantics, so 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 uses a specific verb ('Retorna') and resource ('métricas agregadas de um agente'), then lists the concrete metric families: LLM calls, tool usage, and sessions. It also explicitly distinguishes itself from get_tenant_health, so an agent can tell this tool apart from a closely related sibling.

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?

It states the intended use case: 'monitorar performance e custos de um agente em produção.' It also gives an explicit exclusion with an alternative: for tenant infra health, use get_tenant_health. This gives clear when-to-use versus when-not-to-use 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that it returns full details including usage statistics, but does not disclose behavioral aspects like authentication requirements, error behavior for unknown key_id, or whether the raw key secret is returned.

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?

A single, front-loaded sentence that states the action and enumerates the return fields without any filler. Every part of the sentence contributes useful 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?

For a one-parameter, read-only operation, the description compensates for the missing output schema by listing the returned fields (name, status, role, rate limits, usage stats, tenant). The annotations cover the side-effect profile, so an agent has enough to invoke this tool correctly.

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 already documents key_id as 'UUID da API Key' with 100% coverage. The description adds no additional meaning about the parameter, so the baseline of 3 applies.

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 uses a specific verb ('Retorna') and resource ('uma API Key específica'), and lists the exact fields returned (nome, status, role, rate limits, estatísticas de uso, tenant associado). This clearly distinguishes it from list_api_keys by emphasizing specificity.

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 word 'específica' implies this tool is for fetching one key by ID, contrasting with listing, creating, updating, or deleting API keys among siblings. However, it does not explicitly state alternatives or when-not-to-use, so it is clear but lacks explicit 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds the specific return fields, which is useful behavioral context, but it does not disclose error handling, not-found behavior, or whether an inactive policy is still returned. For a simple read operation, this is adequate but not exceptional.

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?

A single concise sentence that leads with the verb and resource, then immediately states the scope and return fields. Every word contributes information; there is no filler or repetition of schema details.

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 single-parameter read tool with no output schema, the description covers the key elements: what it returns (fields) and how it identifies the resource (by ID). It omits edge cases like non-existent policies or inactive records, but these are minor for such a simple operation, and annotations already confirm the read-only 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% and the single parameter policy_id is well documented as 'UUID da política'. The description's 'por ID' aligns with the parameter meaning but adds no new semantics beyond what the schema already provides. 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 names a specific verb ('Retorna' = returns), a specific resource (approval policy), and a distinct scope (by ID). It also lists the returned fields (name, stages with approvers, is_active), making it easy to distinguish from list_approval_policies, create_approval_policy, and update_approval_policy even without naming them.

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 'por ID' implies the tool should be used when a specific policy_id is known, contrasting implicitly with list_approval_policies. However, the description does not explicitly state when to use this tool vs alternatives, nor does it provide any exclusions or conditions. The usage guidance is implied rather than stated.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is established. The description adds meaningful behavioral context by specifying that results are aggregated across sessions and agents and by listing the included data fields, going beyond the 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, focused sentence that front-loads the purpose and then lists the return fields compactly. Every part adds information, with no filler or repetition of the tool name or annotations.

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 low-complexity, single-parameter read-only tool, the description provides a solid summary of the return payload since there is no output schema. The only minor gap is the lack of detail on field types or formats, but the enumerated fields are sufficient for an agent to understand what the tool returns.

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 single parameter consumer_key is fully described in the schema, including normalization expectations and its equivalence to agent_sessions.consumer_key. With 100% schema description coverage, the tool description does not need to add parameter details, so the baseline of 3 applies.

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 uses a specific verb and resource ('Retorna o perfil agregado de um consumidor') and enumerates the returned fields, making the tool's function clear. It conveys a distinct scope ('cross-session, cross-agent') that separates it from session-specific siblings like get_session_history, but it does not explicitly name or contrast any sibling.

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 an aggregated, cross-session, cross-agent profile of a single consumer is needed. It provides no explicit guidance on when not to use it or which alternative to choose (e.g., list_consumers, list_consumer_sessions, get_session_history).

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 establish readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is known. The description adds that results include rules and exceptions, which is useful given the lack of an output schema, but it goes no further into behavior such as error cases or response shape.

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, front-loaded sentence that states the resource, depth of detail, and included content without any filler. Every part contributes useful 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?

For a simple read-only lookup by ID, the description plus annotations are largely sufficient. The absence of an output schema is partially mitigated by mentioning rules and exceptions, though a fuller listing of returned fields would make it more 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?

The single parameter csp_id is fully documented in the input schema with type, format, and a description, so schema coverage is 100%. The tool description adds no additional meaning or usage detail about the parameter 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 uses a specific verb ('Retorna') with a clear resource ('detalhes completos de uma política de segurança') and specifies the content scope ('incluindo regras e exceções'). This clearly distinguishes it from list-style siblings like list_csps and get_effective_csps.

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 the tool is used when a single CSP's full details are needed by providing a csp_id. However, it does not explicitly mention when to prefer it over alternatives such as list_csps or get_effective_csps, nor does it state any 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 declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds meaningful behavioral context by specifying the resolution order tenant → team → agent → user and the override rule, which is not present in the schema or 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?

Two concise, front-loaded sentences carry all essential information. There is no repetition of schema details or annotation content.

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 description plus schema gives an agent enough to select and invoke the tool: purpose, scopes, and resolution behavior are clear. It does not explain the output shape or whether parameters can be combined, but this is a read-only resolution tool and these gaps are minor.

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 each parameter is already described with its scope ('UUID do time para resolver CSPs no escopo team', etc.). The description adds the inheritance ordering but no additional per-parameter semantic detail.

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 uses a specific verb ('Retorna') and names the exact resource ('políticas efetivas') for a specific context. The mention of scope inheritance and hierarchy clearly differentiates it from sibling tools like get_csp or list_csps.

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?

It clearly states when this tool is appropriate: when a caller needs resolved/effective policies after applying scope inheritance. It does not explicitly name alternatives or exclusions, but the context is unmistakable.

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, and the description adds real value on top: the semantics of cached vs cache_creation tokens, the 1.25x write-cost, why summary.cache_creation_tokens matters for cost_usd reconciliation, and that execution.metadata is null when the caller sent no correlation data. This is unusually rich disclosure for a read tool, though it does not cover pagination or result-size limits.

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?

Front-loads the purpose in the first sentence, then layers detail in a logical order (timeline contents, cache fields, cost caveat, metadata, id sourcing). It is dense and a touch long, and the internal ticket reference '(era a #344)' is noise an agent cannot act on.

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?

There is no output schema, so the description must carry the return-shape burden and it does: it names the timeline, per-call fields, cache token fields, summary aggregation, and metadata correlation. An agent has enough to call it and interpret the result without guessing.

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% and the single parameter is fully documented in the schema, including that it accepts an agent_executions id or a root_execution_id. The description repeats that same guidance rather than adding new syntax or format detail, so the baseline of 3 applies.

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?

States a specific verb+resource and enumerates exactly what the trace contains (chronological timeline of LLM and tool calls with tokens, latency, model, finish_reason). It is clear what the tool returns, but it never distinguishes itself from the similarly named sibling get_execution_trace, which an agent would reasonably confuse it with.

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?

Gives concrete entry context: use the execution_id from agent_executions.id or the root_execution_id returned by chat_with_agent. That is a clear 'when to use' signal. It stops short of any exclusions or pointing to get_execution_trace as the alternative, so it is not a full 5.

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 the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the description only needs to add behavioral context beyond that. It adds the output structure (supervisor→subagents tree with phases, tool calls, cost per node), which is valuable. Minor gaps like invalid-id behavior are not disclosed, but the read-only and idempotent nature is well covered by 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?

Two sentences with no redundancy. The main purpose and output are front-loaded in the first sentence, and the routing guidance in the second adds direct value without padding.

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 single-parameter read-only tool, the description explains what it does, what input it expects, what it returns, and which sibling to use in the alternative case. The annotations cover safety and idempotency. Nothing essential is missing for the agent to invoke it correctly.

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%, meaning the schema already fully documents root_execution_id as 'UUID da execução raiz'. The description reinforces its role in building the trace but adds no new parameter-specific details. Baseline 3 is appropriate since the schema carries the semantic weight.

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 uses a specific verb ('Trace') and resource ('execução multi-agente'), and specifies exactly what it produces: a hierarchical supervisor→subagents tree with phases, tool calls, and cost per node. It also distinguishes itself from the sibling get_session_agent_tree by explicitly stating when that tool should be used instead.

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 clear when-to-use guidance (when you have root_execution_id) and explicit when-not-to-use guidance ('Use get_session_agent_tree quando tiver o session_id em vez do execution_id'). This routes the agent to the correct sibling without relying on inference.

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, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe, non-mutating operation. The description adds only marginal context by stating what the response covers (configuration and capabilities), but says nothing about error behavior for unknown IDs or response shape. Given that annotations carry the safety profile, a 3 is appropriate.

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?

A single, front-loaded sentence with zero filler. It states the action and the scope of the returned data compactly. Nothing could be trimmed without losing meaning, and it is correctly sized for a one-parameter read tool.

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 low-complexity, single-parameter read with strong annotation coverage (readOnly, idempotent, non-destructive), the description is nearly complete: it identifies the target, the parameter, and the scope of returned details. The absence of a return-format description is a minor gap given there is no output schema, but it does not obstruct correct invocation.

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% — the schema already documents mcp_server_id as 'UUID do MCP server' with a uuid format. The description adds nothing about the parameter beyond the schema, so the baseline 3 applies. Since the single parameter is fully documented in the schema, no compensation 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 states a specific verb ('Retorna' – returns) and resource (complete details of an MCP server), naming the returned content (configuration and capabilities). It is clearly distinguished from CRUD siblings like create/update/delete_mcp_server and from test_mcp_server. It does not explicitly differentiate from list_mcp_servers, but the get-vs-list distinction is easily inferred.

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?

No guidance is given on when to use this tool versus alternatives such as list_mcp_servers (for enumeration) or test_mcp_server (for connectivity checks). The description implies usage only by restating the function; there are no exclusions, prerequisites, or selection criteria to help an agent choose correctly among the many mcp_server siblings.

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, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds useful context by specifying what status information is returned and that it reflects the current state, which is valuable because there is no output schema. No contradiction 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?

Two brief sentences lead with the core action and resource, then detail the key output categories. Every word earns its place; no fluff or redundant restatement of the title.

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 no-parameter, read-only status tool without an output schema, the description adequately conveys the return scope. It could be more precise about the exact shape of jobs/statistics, but it gives enough for an agent to invoke it and interpret the general response.

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 zero parameters and the schema adds no burden, so the baseline of 4 applies. The description does not need to explain parameters and does not omit anything relevant.

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 uses a specific verb ('Retorna') and identifies the resource ('SchedulerService') and the exact kind of information provided (active jobs, upcoming executions, statistics). It clearly distinguishes this as a status/observation tool among the large set of scheduler, trigger, and health-related siblings.

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 the tool is for checking scheduler health and activity, but it does not explicitly state when to use it over alternatives like get_tenant_health, list_triggers, or list_trigger_executions. There is no when/when-not guidance, but the intended context is reasonably clear from the content.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds some value by noting that the response includes schema_data, but it does not disclose other behavioral details such as not-found behavior or required permissions.

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 focused sentence with no filler. It front-loads the main purpose and mentions the notable response field without 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?

For a simple read-only getter with one well-documented UUID parameter and safety annotations, the description is largely sufficient. It lacks explicit context about when to prefer this over list_schemas and does not describe error cases, but the tool is simple enough that this is a minor gap.

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%: the only parameter, schema_id, is already described as 'UUID do schema'. The description adds no additional meaning to the parameter itself, so the baseline of 3 applies.

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 a specific operation ('Retorna') and resource ('schema'), and explicitly mentions schema_data in the response. It is unambiguous but does not actively distinguish itself from siblings like list_schemas or validate_schema_data.

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?

There is no guidance about when to use this tool versus list_schemas, create_schema, or validate_schema_data. The intended usage is only implied by the verb and the required schema_id parameter.

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 establish read-only, idempotent, non-destructive behavior. The description adds meaningful behavioral context: the tree spans all turns, uses parent_session_id for lineage, and is suited to multi-turn sessions where execution traces are incomplete.

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 concise sentences front-load the core concept and then explain the relevant usage context. The internal reference '#227' is minor noise, but overall the description is efficient and readable.

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 read-only tree query with one required parameter, the description and schema together provide enough to select and invoke the tool. It does not describe return shape or potential size, but no output schema exists and the key semantics are covered.

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 the schema already documents both session_id and execution_id. The description reinforces the session-anchor concept but adds no parameter-level detail 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 clearly identifies a session-scoped agent tree built from parent_session_id lineage, including supervisor and subagents across turns. It partially differentiates from per-execution tracing, but does not explicitly name or distinguish it from sibling tools like get_execution_trace or get_agent_lineage.

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 a clear usage context: multi-turn sessions where an execution-level trace does not fully represent the tree. It implies the contrast with per-execution tracing but does not explicitly name the alternative tool or state when not to use this one.

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, idempotentHint, and destructiveHint, so no safety contradiction exists. The description adds meaningful behavioral context beyond the annotations: it explicitly states that technical/tool-call messages are filtered out and only user/assistant interactions are returned, which is valuable for an agent deciding whether this tool fits the task.

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 only two sentences, each earning its place: the first states the primary function and resource, and the second clarifies the filtering behavior. It is concise, front-loaded, and free of filler or redundant restatements of the tool name.

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 tool with one well-documented parameter and read-only/idempotent annotations, this description is complete. It specifies the exact resource, the session identifier concept, and the output filtering behavior. There is no output schema, but the description sufficiently explains what the caller will receive, and no critical calling context is missing.

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 session_id parameter is already described in the schema, including where the ID comes from. The description does not add extra parameter meaning, but it does use the phrase 'de uma conversa', which reinforces that session_id identifies a conversation. With full 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 uses a specific verb ('Retorna') and resource ('o histórico de mensagens de uma conversa'), making the tool's function immediately clear. It further differentiates the tool by stating it filters tool-call messages and returns only user/assistant interactions, which separates it from raw trace or execution-history tools.

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 implies this tool is meant for retrieving cleaned, user-facing conversation history for a given session. However, it does not explicitly state when to prefer this over alternatives, nor does it name any alternatives or exclusions, such as when a technical/raw history tool like get_execution_trace would be more appropriate.

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, and non-destructive behavior. The description adds the conditional result has_trigger=false for sessions not originating from a trigger, which is useful behavioral detail beyond the annotations and does not contradict them.

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 short sentences with no filler. The core verb, resource, and conditional return behavior are all front-loaded, and each clause 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?

Even without an output schema, the description conveys the main return values: trigger, execution, and has_trigger flag. It does not specify error handling for invalid or missing session_id, but that is a minor gap for a simple read-only lookup.

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's session_id description is circular ('session_id da sessão'), so the description adds meaning by explaining that this parameter is the starting point for tracing back to the originating trigger and execution. It doesn't add format or constraints, but for a single string identifier that is acceptable.

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?

Clear verb+resource: it returns the trigger and originating execution for a given session_id, plus a has_trigger flag. It is not explicitly contrasted with sibling tools, but the reverse-navigation wording makes its unique purpose identifiable.

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?

Usage context is implied ('a partir de um session_id', reverse navigation), so an agent can infer when to call it. It does not name alternatives or state when not to use it, so guidance is contextual rather than explicit.

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, idempotentHint, and destructiveHint=false, so the core safety profile is covered. The description adds no behavioral nuance beyond the listed return content; it does not mention pagination, size, permissions, or error behavior, but it also does not contradict the 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, compact sentence that front-loads the operation and resource, then lists the relevant content areas. There is no filler or 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?

For a one-parameter read-only retrieval tool without an output schema, the description gives a useful overview of the return content (agent state, schemas, triggers, MCP servers). It is complete enough for correct selection and invocation, though it does not fully specify the response structure or edge-case behavior.

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% and the single parameter snapshot_id already has a clear UUID description. The description adds that the snapshot is a 'publication snapshot', which gives useful context, but otherwise does not add meaning beyond what the schema already provides. 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 states a specific action ('Retorna') and a clear resource ('detalhes completos de um snapshot de publicação') and enumerates meaningful content categories (agent state, schemas, triggers, MCP servers). This distinguishes it from list-style siblings like list_snapshots and from mutation tools like rollback_snapshot.

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 this tool should be used when a complete snapshot's details are needed, and the verb 'Retorna' suggests a read/retrieval operation. However, it does not explicitly state when to prefer this over alternatives such as list_snapshots or get_version, nor does it provide any 'not for X' 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds useful context about what is returned (infra errors, grouped by canonical code) and what is excluded (agent-specific errors). No contradiction. Could mention output shape more explicitly, but this is adequate.

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 short sentences with no filler. The core scope is front-loaded, examples are parenthesized, and the sibling comparison is at the end. Every word 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?

For a simple read-only tool with two optional parameters, the schema covers parameter semantics, annotations cover safety, and the description covers data scope and grouping. The relationship to get_agent_metrics completes the context. Nothing critical is missing.

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%: both start_date and end_date have descriptions in the schema. The tool description adds no parameter-specific semantics beyond the schema, so the baseline of 3 applies.

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 states a clear domain and scope: tenant-level infrastructure health, showing errors not attributable to a specific agent (rate limit, provider auth, infra), grouped by canonical code. It explicitly differentiates from get_agent_metrics, which is per-agent, so an agent can distinguish this tool without opening the schema.

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 names get_agent_metrics as the complementary sibling and gives a decision rule: use this tool for errors not attributable to a specific agent, as opposed to per-agent metrics. This is explicit when-to-use guidance with 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 disclose readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds some value by specifying the returned content (configuration and statistics), but it does not describe error behavior, permissions, or other behavioral 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?

The description is a single, focused sentence that conveys the action, resource, and the scope of returned data 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?

For a simple single-parameter read tool with strong annotations, the description is adequate: it states what the tool returns and that it covers configuration and statistics. It could be slightly more complete by explicitly mentioning that it fetches one trigger by ID, but the schema supplies that detail.

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%: the only parameter, trigger_id, is already documented as a UUID. The description does not add additional meaning to the parameter, so the baseline score of 3 applies.

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 states a specific verb ('Retorna') and resource ('um trigger'), and adds that it returns complete details including configuration and statistics. This is clear, though it does not explicitly distinguish itself from sibling tools like list_triggers or get_trigger_execution.

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 the tool is used when complete details of a single trigger are needed, and the required trigger_id clarifies the by-ID usage. However, there is no explicit guidance about when to use this tool instead of alternatives such as list_triggers or test_trigger.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds some behavioral context about the kind of data returned, but it does not disclose potential costs, errors, or limitations of retrieving 'enriched 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?

The description is a single, well-structured sentence with no filler or redundancy. It front-loads the main purpose and then compactly lists the enriched content categories, so every word 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?

For a read-only tool with one required parameter and safety annotations, the description is largely sufficient: it names the resource and the categories of returned data. Since there is no output schema, slightly more detail about the return shape or format could improve completeness, but the current description is adequate for invocation.

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 execution_id is already documented as 'UUID da execução'. The description does not add meaningful semantics beyond what the schema provides, so the baseline of 3 applies.

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 uses a specific verb ('Retorna') and a clear resource ('detalhes enriquecidos de uma execução'), and it enumerates what the details include: correlated session, LLM calls, tool calls, and aggregated metrics. It does not explicitly differentiate from siblings such as list_trigger_executions or get_execution_trace, but the purpose itself is clear.

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?

No guidance is provided about when to use this tool versus close siblings like list_trigger_executions, get_execution_trace, or get_execution_diagnostics. There are no exclusions, prerequisites, or alternative conditions mentioned, so the agent must infer usage from the tool name alone.

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 convey read-only, idempotent, and non-destructive behavior. The description adds value by revealing what the response contains—before/after data and changed fields—which is useful context beyond the annotations. No contradiction exists.

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?

A single, dense sentence that front-loads the action and resource, then adds the key output details. No wasted words or restatement of the title.

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?

This is a simple read-only getter with fully documented required parameters. The description partially compensates for the absent output schema by naming the main response contents, though it does not describe possible error behavior or the overall response envelope. Still, it is adequate for invocation.

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?

All three parameters have schema descriptions covering 100% of the parameter space, so the baseline is 3. The description does not add parameter-level detail, but none is needed given the schema coverage.

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 uses a specific verb ('Retorna') and a clear resource ('versão específica de um recurso'), and it states the distinguishing output ('dados before/after e campos alterados'). This separates get_version from list_versions and compare_versions without needing to inspect the schema.

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 'versão específica' clearly indicates this tool is for retrieving one version's details rather than listing or comparing versions. It provides clear context but does not explicitly name alternatives or exclusion conditions, so it stops short of a 5.

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 idempotentHint=true and destructiveHint=false, and the description adds useful mechanism-level behavior: it resets metadata in the DB to force reconnection, and works even without an MCP client active. This goes beyond what the annotations convey. No contradiction with annotations 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 compact and front-loaded with the primary action, followed by a scannable bulleted list of use cases and a clear explanation of parameter behavior. Every sentence adds meaningful guidance without 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 the tool has only one optional parameter, no output schema, and annotations covering idempotency/safety, the description fully equips an agent to decide when to call it and what will happen. It covers scope, side effects, and prerequisite-free behavior.

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 covers the sole mcp_server_id parameter 100% with a clear description, and the tool description further enriches semantics by explaining the difference between omitting the parameter (invalidate whole tenant cache) versus providing it (invalidate only that server). This adds real value over the schema alone.

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 states a specific verb and resource: 'Invalida o cache de tools MCP', and explains concrete trigger scenarios. It clearly distinguishes itself from sibling tools like delete_mcp_server or test_connection by focusing on cache/metadata invalidation rather than server management or connection testing.

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 'Use quando' scenarios for when to invoke this tool, covering tool updates, server issues, and auth configuration changes. It also clarifies that it works without an active MCP client. It does not explicitly mention alternatives or when not to use it, but the usage cases are concrete and 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?

The annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint false). The description adds useful behavioral context: batch operation, all-agents scope, and USD currency. However, it does not disclose return format, pagination, or what happens when agents have no budget, so it doesn't go beyond a 3.

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 short sentences carry the entire definition with no filler. The core purpose and scope are front-loaded, and the 'without N+1' phrase adds practical value without adding bulk.

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 parameterless batch read tool with strong annotations, the description is nearly complete. It states what data is returned (budgets/limits in USD) and for whom (all tenants). The only minor gap is the lack of an explicit response shape or field details, but that is not critical for invoking the tool correctly.

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 zero parameters, and the schema already reflects that (100% coverage). With no parameters to describe, the baseline of 4 applies; the description correctly focuses on behavior rather than 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 names a specific action (list), a specific resource (agent budgets in USD), and an explicit scope (all agents in the tenant, in batch). This clearly differentiates it from sibling get_agent_budget, which is singular, even though that sibling is not named 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?

It tells the agent when this tool is valuable: for a consolidated burn-rate view without N+1 calls. It doesn't explicitly say 'use get_agent_budget for a single agent,' but the batch/all semantics and 'without N+1' make the intended use case clear.

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, idempotentHint=true, and destructiveHint=false, so there is no contradiction. The description adds modest value by clarifying that the timeline covers schemas, triggers, and MCP servers and is filterable by resource type. It does not explain ordering, pagination behavior, auth requirements, or the shape of returned entries.

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 compact, front-loaded with the core action and object, and each clause earns its place. The filterability note is a short, separate sentence that adds useful information without bloat.

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 essential call contract is present: required agent_id, optional resource_type filter, and pagination parameters are all covered by schema and description. However, without an output schema, the description does not clarify what a timeline entry contains, and it does not route the agent away from overlapping history/version tools. It is adequate but not 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 limit, offset, agent_id, and resource_type are already documented in the schema. The description mainly reinforces the resource_type filter through the parenthetical examples, adding little meaning beyond what the enum 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 names a specific resource and action: it returns a 'complete timeline' of changes to an agent, listing examples (schemas, triggers, MCP servers). This makes the tool's purpose easy to identify. It does not explicitly distinguish itself from similar siblings like list_versions or list_snapshots, so it stops short of a 5.

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 this tool is for inspecting agent change history and mentions filtering by resource type. It does not state when to prefer this tool over sibling tools such as list_versions, list_snapshots, or get_execution_trace, nor does it provide when-not guidance. Usage context is present but only implicit.

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, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds only that memories are persistent and enumerates the stored categories; it says nothing about ordering, cursor semantics, or default page size behavior.

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 short sentences, front-loaded with the verb and resource. The second sentence restates the category enum already present in the schema, a minor redundancy, but overall there is no wasted 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?

With no output schema, the description should carry more of the return contract; it names the categories but omits ordering, cursor-based pagination semantics (before = updated_at of last item), and the 200-item cap. Annotations cover the safety dimension, so the remaining gap is moderate rather than severe.

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 every parameter (limit, before, agent_id, category, user_key) is already documented in the schema, including the enum and the default of 50. The description adds no extra parameter meaning, making the baseline 3 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?

States a specific verb and resource ('Lista memórias persistentes de um agente') and enumerates the memory categories returned (fatos, preferências, instruções, contexto), which maps directly to the enum. It is clearly distinguishable from delete_agent_memory, but it never explicitly contrasts with sibling list/read tools.

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?

There is no when-to-use guidance, no note about pagination order, and no mention of how this relates to the sibling delete_agent_memory or to per-agent reads. Usage is only inferable from the verb 'Lista'.

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 establish read-only, idempotent, and non-destructive behavior, so the bar is lower. The description adds tenant scope and return-field context, but it does not disclose pagination, default filtering behavior, or how 'todos' interacts with the archived/unpublished flags.

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 short sentences with no filler. The core purpose is front-loaded, and the return shape is stated efficiently.

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 low-complexity list tool with rich annotations and fully documented parameters, the description is mostly complete. It lacks pagination details and explicit sibling differentiation, but an agent can reasonably select and call it correctly.

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 the baseline is 3. The tool description adds no parameter-level meaning, but the schema already documents each parameter, including the nuanced purpose of include_unpublished.

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 action ('Lista todos os agentes do tenant') and the resource, and it specifies the output fields. It does not explicitly differentiate from the sibling list_published_agents, though 'todos os agentes' implies a broader scope than published-only.

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 no guidance on when to use this tool versus alternatives such as list_published_agents. It does not mention exclusions, prerequisites, or preferred scenarios beyond the generic listing purpose.

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 the tool read-only, idempotent, and non-destructive. The description adds valuable behavioral context beyond annotations: the caller's role determines whether sessions are scoped to the caller or to the entire tenant. No contradiction 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?

Two compact sentences with no wasted words. The core action is front-loaded, and the role-based scoping nuance is placed right after, making the description easy to parse.

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 read-only list operation, the description covers the essential behavior, role scoping, and the required agent_id context is in the schema. The absence of an output schema means return shape is not described, which is a minor gap, but not enough to reduce materially.

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 all six parameters are already documented in the schema. The description adds no parameter-specific meaning beyond that, so the 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 states a specific verb ('Lista') and resource ('conversas recentes com um agente'), and it distinguishes its scope by role: end users see only their own sessions, while operators see tenant-wide sessions. This makes the operation clear without needing to inspect the schema.

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—listing recent conversations for a specific agent—and gives useful role-based context. However, it does not explicitly name alternative sibling tools like list_consumer_sessions or state when not to use this tool, so the agent must infer selection from context.

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, idempotentHint, and destructiveHint=false, so safety is covered. The description adds genuine value beyond them by explaining that the result is the *resolved/effective* toolset (what the agent 'efetivamente terá disponível em runtime'), which is the key behavioral insight an agent needs. It does not mention permissions or pagination, keeping it short of a 5.

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, zero filler, and the core scope (resolved tools of an agent) is front-loaded before the clarifying detail about runtime availability. Every clause 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?

For a read-only, single-parameter list tool with annotations covering the safety profile and no output schema, the description explains both what is aggregated and what the output contains (name, description, parameters). Only the exact output format/pagination is unstated, which is minor here.

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% with a single required agent_id (uuid), so the schema fully documents the only input. The description mentions 'parâmetros' only as part of the output shape, not to add input semantics. Baseline 3 is appropriate when the schema does the heavy lifting.

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 names a specific verb ('Lista') and a precise resource ('ferramentas resolvidas de um agente') and clarifies scope by enumerating the three sources it aggregates (api_config + MCP tools + core tools). This clearly separates it from siblings like list_mcp_servers or list_agent_memory, which operate on raw configurations rather than the agent's effective runtime toolset.

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?

Usage is only implied: an agent can infer you call this to inspect what tools an agent will actually have at runtime, but there is no explicit when-to-use guidance and no alternative sibling is named (e.g., list_mcp_servers for the raw server list). Nothing misleading, but nothing routing either.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value by disclosing the return contents (id, name, status, prefix, suffix, rate limit, statistics), which is especially useful given no output schema. It does not contradict the 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, front-loaded sentence: the verb and scope come first, followed by the return field list. Every phrase adds information, and there is no fluff or repetition.

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, parameterless, read-only listing tool, the description provides the tenant scope and return fields, and annotations cover the behavioral safety profile. A minor gap is the absence of pagination or response shape details, but these are not essential for basic invocation.

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 zero parameters, so there is no parameter semantics to document. The description reinforces the no-argument, tenant-wide listing behavior and describes what is returned, which is sufficient for a parameterless tool. Baseline for 0 params is 4.

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 uses a specific verb and resource: 'Lista todas as API Keys do tenant', clearly identifying the listing operation and tenant scope. It also enumerates the returned fields, which helps distinguish it from get_api_key, create_api_key, update_api_key, and delete_api_key.

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 intended use as a tenant-wide listing is implied by 'todas as API Keys do tenant' and the tool name, but there is no explicit guidance about when to prefer this over get_api_key or any mention of pagination/filtering conditions. The usage context is clear but not explicitly contrasted with 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 cover safety (readOnlyHint=true, idempotentHint=true, destructiveHint=false), lowering the burden on the description. The description adds useful domain context about how policies are referenced, but it does not disclose runtime behaviors such as pagination, ordering, or whether the default output includes inactive policies (the schema's 'active_only' param implies this but is not in the description).

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 short sentences with no redundancy. The first sentence states the core operation and scope, and the second provides valuable referential context. The description is front-loaded and every word 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?

For a very simple tool with one optional parameter, no output schema, and no nested objects, the description is nearly complete: it covers the resource, tenant scope, and semantic context. It lacks explicit sibling differentiation, but the clarity of 'políticas de aprovação do tenant (quem aprova o quê)' makes its function clear enough to call correctly.

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 single parameter 'active_only' is fully described in the input schema (description: 'true = apenas políticas ativas') with a default value, so the description does not need to add param-specific meaning. The schema coverage is 100%, and the description adds no additional parameter guidance beyond what the schema already states, warranting the baseline 3.

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 specifies a clear verb ('Lista'), resource ('políticas de aprovação do tenant'), and scope ('do tenant'), and adds a parenthetical definition ('quem aprova o quê') that disambiguates the resource type. The additional note about CSP references via behavior.approval_policy_id further clarifies the role of these policies, distinguishing it from list_approvals, which presumably lists approval records.

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 (to list tenant-level policy definitions) and even hints at its downstream use by CSPs, but it does not explicitly mention alternatives or when not to use it. There is no routing guidance against siblings like get_approval_policy or list_approvals, leaving the agent to infer selection from the name and resource phrasing.

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, idempotentHint, destructiveHint, so the description adds value by explaining role-based visibility and the fact that approve/reject actions are not performed here. This boundary clarifies an important behavioral trait beyond the 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 filler. It front-loads the core function, then adds relevant access-control nuance and a key boundary, all in economical prose.

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?

Combined with rich annotations and full schema coverage, the description covers the key behavioral context: role scoping and the fact that decisions happen elsewhere. It is complete enough for an agent to decide when to call it, though it doesn't mention response shape or pagination, which are minor given there is no output schema and the tool is simple.

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 the parameters limit and status are already fully documented in the schema. The description adds no additional semantic nuance about parameter usage, which is acceptable at the baseline for full schema coverage.

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 states a specific action ('Lista pendências de aprovação HITL do tenant') with a clear resource (approval pending items for tool actions). It further clarifies scope by role (admin/owner vs editor), making it distinct from policy-related siblings like list_approval_policies.

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?

It provides clear context on when to use this tool: to list HITL approval pendings. It explicitly excludes decision-making ('decisão acontece no chat do aprovador, não por esta API') and describes role-based visibility. However, it does not explicitly name alternatives or state when not to use it in favor of other 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, so the safety profile is covered. The description adds useful behavioral context such as tenant scoping, pagination, and ordering by last_seen_at desc, but does not go further into return format or edge cases.

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 core purpose appears immediately and the use-case sentence is useful rather than redundant. 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?

For a simple paginated list tool with four optional, fully documented parameters and no output schema, the description gives sufficient context: scope, ordering, and typical use. It could mention the shape of returned consumer objects, but that is not critical for selecting and invoking the tool.

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 the schema already documents all four parameters. The description does not add extra parameter-level semantics; it only speaks to the overall result set ordering.

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 states a specific verb and resource: 'Lista paginada de consumidores do tenant atual', and adds a concrete ordering ('ordenada por mais recentes (last_seen_at desc)'). It is clearly distinct from siblings like get_consumer_profile (single consumer) and list_consumer_sessions (consumer sessions).

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 clear usage context: 'Útil pra dashboards "consumers ativos" ou ranking'. This tells an agent when the tool is valuable, though it does not explicitly mention alternatives or when not to use it.

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, idempotentHint, and destructiveHint, so safety is covered. The description adds useful behavioral context: cross-agent scope and most-recent ordering. It does not describe what fields the returned sessions contain or pagination behavior, but this is moderate added value given the 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?

Two compact sentences with no filler. The first sentence front-loads the core behavior and qualifiers; the second sentence adds the comparison to get_consumer_profile, which is directly useful for tool selection.

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 list tool, the description plus schema and annotations are sufficient for correct invocation. The main gap is that with no output schema, the agent gets no hint about the shape of the returned sessions, and there is no explicit differentiation from list_agent_sessions.

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 the parameters limit, offset, and consumer_key are already fully documented. The description reinforces 'consumidor específico' as the consumer_key role but adds no new parameter-level 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 action ('Lista'), the resource ('sessões de um consumidor específico'), and key qualifiers ('cross-agent, ordenadas por mais recentes'). It also distinguishes itself from get_consumer_profile by contrasting sessions with aggregate counters.

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?

It explicitly mentions when this tool complements get_consumer_profile, telling the agent that get_consumer_profile only returns aggregate counters while this tool returns actual sessions. However, it does not mention alternative session-list tools like list_agent_sessions or state explicit 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds only the tenant-wide scope and filterability, which are more about purpose than behavior; no extra details on pagination, ordering, or response shape are provided.

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 compact sentence that front-loads the action and resource, then states the filtering capability. There is no redundant wording or filler.

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 list tool with all parameters optional and fully described in the schema, the description is sufficient for correct invocation. The only notable gap is the lack of mention of return shape or pagination, but that is minor for this tool.

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 covers 100% of the parameters with descriptions, so the baseline of 3 applies. The description broadly mentions filtering by scope, type, and status, which maps to scope, policy_type, and is_active, but does not add meaningful detail 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 uses a specific verb ('Lista') and resource ('políticas de segurança (CSPs) do tenant'), making it clear this is a listing operation. It is distinguishable from the singular get_csp and the computed get_effective_csps by saying it lists all tenant policies, though it does not explicitly name those siblings.

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: it lists all tenant CSPs with optional filters by scope, type, and status. It does not explicitly mention when to prefer this over alternatives like get_csp or get_effective_csps, so some inference is required.

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