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?

The description goes far beyond annotations, disclosing synchronous execution, no progressive streaming, use of all configured tools, detailed response fields, timeout error semantics (TURN_TIMEOUT), execution_id correlation with get_execution_diagnostics, and resumability after a timeout. This is rich behavioral context that annotations alone 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 and front-loaded with the core action, then uses line breaks to enumerate response contents and the important session_id guidance. Every sentence adds useful information—no filler, no repetition of schema details already covered.

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 there is no output schema, the description compensates well by enumerating the response fields, explaining timeout behavior, and telling the agent how to correlate executions and maintain session context. For a synchronous agent-chat tool with moderate complexity, this is complete enough to invoke 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 schema already documents all three parameters and their semantics. The description reinforces the session_id behavior ('use o session_id retornado nas próximas mensagens para manter o contexto') but does not add significant new parameter-level meaning beyond what the input schema already states.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with a specific verb+resource: 'Envia uma mensagem a um agente e recebe a resposta completa'. It also differentiates itself by noting the synchronous nature and absence of streaming. However, it does not explicitly distinguish itself from the sibling tool 'send_manual_message', which appears to serve a similar chat/send-message role.

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 about how to maintain conversation state by reusing the returned session_id, and it explains timeout/resume behavior. But it does not provide explicit when-to-use vs. when-not-to-use guidance or name any alternative tools, such as send_manual_message, so the agent must infer when this is the right choice.

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 are all false, so the description carries most of the behavioral burden. It clearly states a create action and adds non-obvious behavior: sensitive fields such as password and keys are masked in the return value, and an ID is returned for downstream use. 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?

Four short, front-loaded sentences each add value: the core purpose, downstream workflow, allowed providers, and output masking. There is no filler or unnecessary 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?

With no output schema, the description usefully explains that the call returns an ID used as connection_id and that sensitive fields are masked. Combined with a fully described input schema, an agent has enough to select and invoke the tool correctly; a fuller return-shape description would be the only meaningful 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%, so the baseline is 3 and the schema already documents every parameter, including provider-specific connection_config structures. The description does not add parameter-level semantics beyond restating supported providers and the masking behavior, so no upward adjustment is warranted.

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 a specific action and resource ('Cria uma nova conexão de banco de dados para o tenant'), which clearly distinguishes this create operation from sibling list/get/update/delete/test_connection tools. It further contextualizes the object by noting the returned ID feeds create_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 gives clear workflow context (the returned ID is used as connection_id in create_schema) and constrains use to supported providers (postgresql, supabase). It does not explicitly name alternatives or exclusion conditions, but these signals are sufficient for selecting the tool in most cases.

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 detail beyond annotations: unknown fields are accepted silently and remain inert, origin policies are stored but never enforced at runtime, tenant_id is injected by the server, and must_not_tools is filtered before turns in both runtimes. No annotation contradiction found.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but information-dense and well organized, with the core purpose front-loaded. Some repetition around schema warnings and rule examples prevents a perfect conciseness score, but every substantial section earns its place given the tool's complexity.

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 create tool with 8 parameters, nested rule objects, and no output schema, the description is exceptionally complete. It covers required fields, per-type shapes, scope behavior, runtime limitations, approval setup, and a formal schema reference. The exact return payload is not described, but that is not necessary for 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?

Even though schema coverage is 100%, the description adds far richer meaning: per-type rules structures with concrete examples, scope_target_id requirements, approval-related fields, and the note that tenant_id is server-injected. This goes well beyond the bare input 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 opening sentence names a specific action and resource: "Cria uma nova política de segurança contextual (CSP)". The scopes and policy types further clarify what the tool is for, and the create verb distinguishes it from sibling update/delete/list 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 gives rich context for when to create CSPs, explains scope inheritance, identifies prerequisites like create_approval_policy, and explicitly warns that origin policies are not a security control. It does not explicitly mention update_csp or list_csps as alternatives, but the usage context is 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 only provide generic hints (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the description carries the burden of behavior. It meaningfully adds transport negotiation details, deprecated SSE behavior, env-var token resolution, and auth/config coupling. It does not cover return values, error cases, or duplicate-name behavior, but the described side effect and constraints are clear.

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 front-loads the core purpose, then uses compact bullet lists for transports, auth/config combinations, and optional config fields. Every section earns its place; there is no filler or repeated 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?

For a tool with 7 parameters, nested objects, enums, and no output schema, the description covers the difficult parts: transport validity, auth/config invariants, defaults, and termination of legacy SSE. Minor gaps remain around return value, validation failures, and what happens if the agent_id or endpoint is invalid, but the essential invocation guidance is 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?

Schema description coverage is 100%, so the baseline is 3, but the description substantially enriches the schema: it specifies exact config object shapes per auth_method, explains vault_secret_id usage, custom api_key_header, the INTERNAL_TUNNEL_TOKEN env var, timeout defaults, headers, and defaults_from_context. This is precisely the information an agent needs beyond the raw JSON 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?

A description begins with a clear verb and resource: 'Registra um novo MCP server para um agente' and states the consequence: the agent will be able to use the server's exposed tools. This distinguishes it from sibling MCP tools like list_mcp_servers, update_mcp_server, and delete_mcp_server by naming the creation action.

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 strong context on when to use each transport and auth option: stdio is 'local, apenas dev', SSE is explicitly deprecated, and tunnel is recommended specifically for MCP servers via Zihin Tunnel. It lacks an explicit pointer to siblings like update_mcp_server for modifying an existing server, so it stops short of full alternative routing.

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 only provide boolean hints (readOnly=false, idempotent=false, destructive=false). The description adds substantial behavioral context beyond those flags: it warns about the API_CONFIG endpoint.name/tool_definition.name equality requirement, describes transformation-field semantics, notes that mcp_tool_config/mcp_resource_config are usually Builder-generated, and recommends a validation workflow to avoid contract errors. It doesn't detail duplicate-name behavior or failure modes, but the annotations already signal non-idempotency, so this is acceptable.

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 long but well-structured and front-loaded: purpose, then type breakdown, then exclusions, then workflow. It earns its length given the schema-type complexity. Minor redundancy exists because much of the schema_data description is repeated from the input schema, but the use of bold headers and bullets keeps it scannable.

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 create tool with seven schema types, complex nested parameters, and meaningful variant behavior, the description is very complete. It covers exclusions (triggers/CSPs), formal contracts, validation workflow, and even notes that MCP configurations are typically Builder-generated. No output schema exists, so the description and schema together give an agent what it needs to call 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?

Schema description coverage is high and the schema itself is very detailed, so the baseline is 3. The description still adds value by summarizing the type-specific schema_data shapes and by covering mcp_tool_config and mcp_resource_config, which the schema_data description in the schema does not detail. It also adds the pointer to the formal contract resource (zihin://schemas/{schema_type}) and the dry-run validation step, which helps an agent construct schema_data correctly.

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 a specific verb and resource: 'Cria um novo schema para um agente.' It also distinguishes itself from sibling tools by explicitly stating that triggers and CSPs are not schemas and should be created via create_trigger and create_csp, which makes the tool's boundary 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?

It gives explicit when-to-use guidance by enumerating the supported schema types and by saying 'Triggers e CSPs NÃO são schemas: use create_trigger e create_csp.' It also provides a recommended workflow: read the formal schema resource, build schema_data, validate with validate_schema_data (dry-run), then create. This is actionable and prevents contract errors.

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?

Annotations only indicate the tool is not read-only, not idempotent, and not destructive; the description adds substantial context: server-side ID injection, strict enum constraints, type-dependent configuration, automatic transform defaults (twiml → strip_markdown/max_length), sender_access semantics, message_buffer debounce, and split_config behavior. 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?

The description is front-loaded with purpose and contract, but it becomes very long and largely reproduces the schema's trigger_config structure with examples. While the added semantics justify some length, several config snippets are redundant with the schema and could be trimmed.

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 purpose, authoritative contract, per-type config structures, enums, defaults, and key behavioral nuances—enough to make correct create_trigger calls. However, it explicitly says to send only four fields while the schema also exposes optional api_key_id and description, and it does not mention response/error behavior, leaving minor gaps.

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 meaning beyond the schema: it tells which parameters are actually expected, enumerates allowed enum values, and explains the effects and defaults of response_adapter.format, sender_access, message_buffer, and split_config. The authoritative contract reference resolves most ambiguity from the inline examples.

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 ('Cria um novo trigger para um agente') with a clear resource (trigger for agent) and points to the authoritative contract. It is easily distinguished from sibling tools such as update_trigger, delete_trigger, and list_triggers.

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 strong usage guidance: send only agent_id/name/trigger_type/trigger_config because the server injects tenant_id and ids, and warns against inventing enum values. It does not explicitly name alternatives or state when to prefer this tool over update_trigger, 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 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 readOnlyHint=false, so the description's 'soft delete' qualifier adds valuable nuance beyond the structured metadata. It clarifies that the operation is not a hard permanent removal, though it does not explain recoverability or downstream visibility.

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 short and front-loaded with the core action and soft-delete behavior. The 'Requer...' sentence is slightly redundant with the required parameter list, but it serves as an at-a-glance checklist without adding unnecessary length.

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 three-parameter destructive operation, the description and annotations give enough context to invoke it correctly. Return-value expectations are not specified, but for a delete-style tool without an output schema this is a minor gap; clarifying soft-delete consequences 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?

Schema description coverage is 100%, so each parameter is already documented. The description only repeats the parameter names without adding format, selection, or usage details beyond what the schema provides, making 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?

The description names a specific action ('Remove (soft delete)') and a specific resource ('uma memória específica de um agente'), which clearly distinguishes it from deleting an entire agent or listing memories. It does not explicitly mention sibling tools, but the object and scope are clear enough.

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_agent_memory or delete_agent. The description only restates the required parameters without providing selection criteria or 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 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?

The annotations already mark the operation as destructive, non-read-only, and non-idempotent. The description adds meaningful nuance by explaining this is a soft delete that leaves the connection inactive but restorable, which goes beyond what the annotations alone 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 two short sentences with no filler. The key action is front-loaded, and the important soft-delete/restore behavior 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 single-parameter mutation with annotations covering its destructive nature, the description is complete enough. It tells the agent what the operation does and what the consequence is, including reversibility, without needing 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?

Schema description coverage is 100%, so the only parameter, connection_id, is already fully documented in the input schema. The description adds no extra parameter-level detail, 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 uses a specific verb ('Desativa') and resource ('conexão'), and clearly qualifies the operation as a soft delete. This distinguishes it from other delete-like tools targeting different resources such as delete_api_key or delete_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?

The description implies the tool is used to deactivate a connection and that the action is reversible, but it does not explicitly state when to use it over alternatives, nor does it mention exclusions or prerequisites. The usage context is largely inferred from the verb and resource.

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?

Beyond the destructiveHint annotation, the description adds crucial behavioral context: deletion is permanent, and dependent api_config and db_config entries will stop working. This directly discloses real-world consequences of invoking the tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two concise sentences with no wasted words. The core action is front-loaded, and the critical warning is placed immediately after, making the most important information 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 single-parameter destructive tool with no output schema, the description is complete: it states the action, the permanence, and the impact on dependent configurations. Nothing essential is missing for an agent to decide whether and how to call 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?

The schema already fully describes the sole 'name' parameter with 100% coverage. The description adds no additional parameter-level meaning beyond referring to the secret to be removed, 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 specific verb and resource ('Remove um secret permanentemente'), making the tool's purpose immediately clear. It also distinguishes itself from sibling tools like create_secret, update_secret, and list_secrets by emphasizing permanent deletion.

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 usage context is implied: use this when you want to permanently delete a secret. However, the description does not explicitly state when not to use it or mention alternatives such as update_secret for modifying rather than removing.

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, idempotentHint, and destructiveHint=false. The description adds useful behavior beyond annotations by disclosing that sensitive fields are masked and that both schema_cache and semantic_cache are included in the response.

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. Every clause adds meaningful information: the action, the returned object, sensitive-field masking, and the included caches.

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 one required parameter, clear read-only annotations, and no output schema, the description provides enough for an agent to call the tool correctly and understand the response contents. It lacks explicit error-handling details and alternative routing, but neither is essential for this simple retrieval operation.

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, connection_id, already has a complete schema description ('UUID da conexão') with 100% coverage. The tool description adds no additional parameter-level meaning, 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 specific verb and resource: 'Retorna detalhes de uma conexão', and enumerates what is included (configuration, schema_cache, semantic_cache). It is clearly a single-connection read operation, though it does not explicitly distinguish itself from siblings like get_connection_schema or get_connection_semantic.

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 explicit when-to-use or when-not-to-use guidance is provided. The singular resource and read-only annotations imply use when needing full connection details, with list_connections as the obvious listing alternative, but this is 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 establish read-only, idempotent, non-destructive behavior. The description adds meaningful context by revealing that the schema is cached, implying possible staleness or emptiness, and by stating the prerequisite to refresh when needed. This goes beyond the structured annotations without contradicting 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?

The description is three sentences with no filler. It leads with the core functionality, then gives the intended use case, then provides the fallback instruction. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple, read-only, single-parameter tool, the description fully covers what the tool returns, when to call it, and what to do when the cache is empty. Given the annotations and complete schema, nothing essential is missing for 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?

The input schema fully documents connection_id with a UUID format and a description, so schema coverage is 100%. The description does not add parameter-level detail, but it does reinforce the connection context. Baseline of 3 is appropriate since 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 uses a specific verb ('Retorna') and identifies the exact resource ('schema em cache de uma conexão') with its contents ('tabelas, colunas, tipos'). It clearly differentiates this cached-schema retrieval from related tools like refresh_connection_schema by explicitly referring to cache and cache-empty fallback.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says when to use the tool ('Use antes de criar db_config') and gives a concrete condition for using an alternative ('Se o cache estiver vazio, use refresh_connection_schema primeiro'). This provides clear decision guidance without leaving it 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 establish that the operation is read-only, idempotent, and non-destructive. The description adds useful behavioral context by explaining what the semantic cache represents and how the returned data is used, going beyond the annotations without contradicting 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?

The description is compact and well-structured: it leads with the action, explains the purpose, and provides the return format in a clear example. Every sentence contributes meaningful information 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 retrieval tool with one well-documented parameter and no output schema, the description is complete. It specifies the return structure, the purpose of the cache, and the role in auto-routing, which is enough for an agent to 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?

The single parameter connection_id is already fully documented in the schema with type, format, and description, yielding 100% schema coverage. The tool description adds no extra parameter-level meaning, which corresponds to the baseline of 3 for fully covered schemas.

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 verb ('Retorna'), a specific resource ('cache semântico de uma conexão'), and the exact contents (domains, keywords, business context). It also distinguishes itself from the sibling get_connection_schema by naming the semantic cache and its purpose in auto-routing.

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 clear context for when this tool is relevant: it explains that the semantic cache is used by auto-routing to select the correct data source. However, it does not explicitly state when not to use it or point to alternatives, 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 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds useful detail about the output contents, though it does not disclose any additional behavioral caveats such as pagination, limits, or failure modes. This is adequate given the annotation coverage.

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 that front-loads the tool's purpose and enumerates the returned diagnostic fields. There is no filler or duplication of schema 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 read-only, single-parameter tool with no output schema, the description adequately explains both the input provenance and the output structure. It is sufficiently complete for an agent to select and call the tool correctly, though it could briefly note the relationship to get_execution_trace.

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 that execution_id is a UUID. The description adds valuable semantic context beyond the schema by clarifying that execution_id can be either the agent_executions id or the root_execution_id returned by chat_with_agent, which helps the agent select the correct value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the tool's function: returning a complete diagnostic trace of an execution, including a chronological timeline of LLM and tool calls with tokens, latency, model, and finish_reason. It is specific and action-oriented, but it does not explicitly distinguish this tool from the similarly named sibling get_execution_trace.

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 clear context on what input to supply and where that input can be sourced: the execution_id field from agent_executions or the root_execution_id returned by chat_with_agent. It does not mention when to prefer this tool over alternatives like get_execution_trace, but the selection context is otherwise unambiguous.

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, idempotentHint, and destructiveHint=false, so the safe-read nature is covered. The description adds the memory category types, but omits the `schedule_report` category present in the schema, which is a minor transparency gap.

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 action is front-loaded and the return categories are listed efficiently. 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?

The tool is a list operation with no output schema, so the description should convey more about the return structure or pagination, but it does not. It is also missing the `schedule_report` category, making it incomplete against 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 baseline is 3. The description adds meaning by mapping the return content to `fact`, `preference`, `instruction`, and `context`, but it does not mention `schedule_report` and does not clarify `agent_id` or `user_key` 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 the action ('Lista') and the resource ('memórias persistentes de um agente'), and enumerates the return categories: facts, preferences, instructions, and context. It is distinct from the nearest sibling `delete_agent_memory`, though it does not explicitly differentiate itself from `list_agent_history` or `get_session_history`.

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 alternatives like `list_agent_history`, `list_agent_sessions`, or `get_agent`. The description only states what it does, not the conditions under which it is the right choice.

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 (readOnlyHint, idempotentHint, destructiveHint) already convey the non-mutating nature. The description adds valuable context beyond annotations by specifying the output contents (name, description, parameters) and the runtime scope (api_config + db_config + MCP + core). It does not contradict annotations and provides useful behavioral detail about what the tool returns, so a 4 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?

The description is two sentences with no redundancy. The first sentence front-loads the primary action and scope, and the second efficiently lists output details. Every clause earns its place, making it highly concise and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description compensates by explicitly stating that the tool returns the agent's resolved tools with name, description, and parameters. It covers the input (agent_id), the scope (resolved tools), and the output content. For a simple read-only listing tool, this is complete — an agent knows exactly what to expect and how to invoke it. No critical 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% — the only parameter, agent_id, is already described as 'UUID do agente'. The description does not add any additional semantics beyond restating 'de um agente'. With full schema coverage, the baseline is 3, and the description adds no extra meaning to the parameter, so it stays at 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 clearly states the specific action: listing all resolved tools of an agent, and enumerates the composition (api_config, db_config, MCP tools, core tools). It differentiates from siblings like list_agents or get_agent by focusing on tool inventory rather than agent metadata. The phrase 'Mostra o que o agente efetivamente terá disponível em runtime' clarifies the scope and output, making the tool's purpose 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?

The description provides clear context: this tool is for listing an agent's resolved toolset at runtime. However, it does not explicitly mention when to prefer this over siblings like list_agents or get_agent, nor does it state any exclusions. The context is clear enough for an agent to infer the use case, but without explicit alternatives or when-not-to-use guidance, 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 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.