NEXUS AGI

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, but the description adds real context: activation is idempotent for already-active goals, unknown/other-status goals raise errors, and an active goal without a plan surfaces in get_planning_requests until submit_goal_plan is used (or NEXUS auto-generates it). This downstream side-effect disclosure goes well 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?

Front-loaded with the core action and its preconditions before the workflow context; each sentence adds signal. The plan-related paragraph is slightly tangential for a tool whose job is activation, but it is genuinely useful for anticipating what happens next, so the cost is minor.

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 an output schema present, return values need no explanation, and the description covers preconditions, idempotency, error behavior, and the plan/task workflow handoffs. Nothing an agent needs to invoke this correctly 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 0% for the single parameter (schema only declares it as a string), so the description must carry the load and it does, specifying that goal_id is a UUID of the goal. That is the essential format hint, though nothing more (e.g., how to obtain the UUID, e.g. via list_goals/get_goal) is offered.

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 first sentence states a specific verb (activate) and resource (goal) plus the exact statuses it applies to, which cleanly separates it from close_goal, pause_goal, and update_goal. It also names the error outcome for other/unknown statuses, so an agent knows precisely what this tool does.

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 an explicit precondition (goal must be in 'draft', 'blocked', or 'paused') and states that already-active goals are returned unchanged while other statuses error, which is effectively a when-to-use/when-not rule. It stops short of explicitly routing the agent to pause_goal/close_goal for the opposite direction, so it is clear context without full alternative coverage.

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 cover the safety profile (write, non-idempotent, non-destructive), and the description adds real context beyond them: comments persist and are visible in get_task and the NEXUS web console. The 5000-character limit is also disclosed. It does not describe error behavior for an invalid task_id, so it is not fully exhaustive.

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

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

Front-loaded with the action, then behavior, then a clean Args block. Efficient overall, though the Args section slightly restates parameter names that are already visible in the schema.

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

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

For a 3-parameter write tool with no output schema, the description covers purpose, all parameters, defaults, and where the comment appears. It omits only edge-case behavior (e.g., failure on unknown task_id), which is minor given the annotations and schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description carries the full burden and does so well: task_id is documented as a UUID, content as text up to 5000 characters, and author enumerates the valid values ('agent' default, 'user', 'system'). This adds constraint and enum detail absent from the schema.

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

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

States a specific verb ('Add') and resource ('a comment ... to a standalone task'), and the parenthetical (progress notes, findings, context) clarifies what a comment is. The 'standalone task' qualifier hints at scope, but it does not explicitly differentiate from siblings like update_task or create_task.

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 explicit when-to-use or when-not-to-use guidance, and no sibling is named as an alternative. Usage is only implied by the content examples and by stating where comments surface (get_task, web console).

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

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

Goes well beyond the annotations by disclosing concrete effects: resets the rule's staleness clock, restores confidence to the configured maximum, and removes the rule from the review queue. These side effects are the key behavioral traits an agent needs and are not derivable from readOnlyHint/idempotentHint alone.

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

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

Front-loads the core action in the first sentence, then the rationale and effects, ending with a tight Args section. Every sentence carries information; nothing is redundant 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?

With no output schema and only one required parameter, the description supplies everything needed to call the tool correctly: what it does, when to use it, what changes as a result, and the parameter's meaning.

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 0% and the schema only types rule_id as a string, but the description compensates by specifying it is the UUID of the verified rule, adding format/identity meaning. With a single parameter this is sufficient, though no extra validation or lookup guidance is given.

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

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

States a specific verb (affirm/record) and resource (rule), and precisely defines the act as verifying a rule against current state. It is clearly distinguishable from siblings like create_rule, list_rules, and evaluate_hypothesis, which an agent can tell apart 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?

Explicitly states the when-to-use condition ('rules actually verified as correct') and the anti-condition ('not for rules that were merely retrieved or look plausible'). It also frames the motivation: rules decay and low-confidence rules get queued for review.

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

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

Annotations only cover safety (readOnlyHint=false, idempotentHint=true, destructiveHint=false); the description adds the real consequence model: 'vigente' closes the other relation, ontology answers update the ontology, and fusion is explicitly reversible. It also discloses timing side effects ('posponer' hides for 3 days, 'investigar' for 7), which is exactly the kind of behavior annotations can't express.

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

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

Front-loaded with the core action, then a structured Args block with no filler sentences. It is long, but the length is justified by 0% schema coverage; a small amount of nesting in the respuesta line makes it slightly denser than ideal.

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 7-parameter mutation tool with no output schema and no per-parameter schema docs, the description supplies every decision an agent needs: which answers are valid, which extra args each requires, and what each answer does. Nothing material is left unspecified.

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 0% across 7 parameters, so the description carries the full burden and does so well: each of tipo, question_id, respuesta, relation_id, parent, conservar, and por_usuario is explained, including which respuesta values pair with which tipo and the default for conservar and por_usuario.

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

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

States a specific verb and resource ('Apply an answer to a question returned by get_next_question') and ties the input to a named sibling that produces it. It also enumerates the three question families (contradiccion/ontologia/fusion), so an agent can distinguish it from get_next_question (fetch) and the lower-level relation 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 entry condition is explicit: only use it for questions produced by get_next_question, with per-tipo choices spelled out. It falls short on sibling differentiation -- it never says when to use this versus resolve_contradiction, decide_merge_proposal, or ratify_relation, which all touch the same contradiction/merge space.

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

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

Goes well beyond the annotations: discloses that every call is logged as an evaluation for the account, that detalle is stored truncated with secrets masked ('never whole'), that a verdict has a validity window (vigencia_segundos, 0 when not allowing), and that no_hacerlo extends to 'other ways of reaching the same effect'. The logging/truncation disclosures are exactly the kind of side-effect detail annotations cannot carry.

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

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

Front-loaded with purpose, scope, then return shape, then args — a sensible order, and the verdict enumeration earns its length since there is no output schema. It runs long, and the sentence 'record_procedure_usage records the outcome of a returned procedure' sits orphaned between the return contract and the args without explaining when to call it.

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

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

With no output schema and a 9-parameter schema with zero descriptions, the description must cover everything — and it does: return fields are enumerated with meanings, all four verdicts are defined, and the logging/masking behavior is stated. An agent can call this correctly and interpret the result from the description alone.

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 0% across 9 parameters, so the description carries the full burden — and does: every parameter is given operative meaning, including why intencion and riesgo_percibido exist, that clave comes from a hook stop point, and that detalle is masked and truncated. This fully compensates for the empty 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?

Specific verb and resource: 'look up the user's stored rules, procedures and past mistakes that apply to an action the agent is about to take, and return a verdict'. The outcome (a veredicto with four named values) makes the tool unmistakably a pre-action gate. It does not, however, name or contrast with the closest siblings (match_procedures, get_procedure, list_rules), so it stops short of full sibling differentiation.

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

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

Explicit inclusion criteria in plain operational terms — reaching someone else, committing the person, irreversible, shared/official, sensitive data, acting in the person's name — plus an explicit exclusion: 'Reading, searching and drafting are outside its scope.' The consultar=True/False split further tells the agent which mode to pick and why.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, and the description adds meaningful side-effect detail beyond them: a closing event and reason are written to history and a version snapshot is saved, and the closure is irreversible. The remaining gap is that it never explains what happens on a repeated close (error vs. no-op) despite the idempotentHint claim, nor any permission requirements.

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

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

Purpose is front-loaded in sentence one, behavior and the pause_goal alternative follow, and parameters are gathered into a compact Args block. Every sentence carries information; nothing is repeated from the title or restates the 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?

An output schema exists, so return values need not be described. For a 3-parameter terminal mutation tool, the description covers purpose, irreversibility, side effects, the sibling alternative, and every parameter constraint — nothing an agent needs in order to call it correctly 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 0% and the schema carries no enum on final_status, so the description does the full job: it documents goal_id as a UUID, enumerates all four allowed status values, and states the conditional rule that reason is required for 'failed' and optional otherwise.

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 first sentence states a specific verb and resource ('Close a goal') plus the scope of the action ('with a terminal status, ending its pursuit'). It explicitly separates itself from the sibling pause_goal and implicitly from update_goal, so an agent can pick it without opening any schema.

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

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

It names the alternative tool and the condition that selects it: 'to stop work temporarily use pause_goal instead.' Combined with 'A closed goal cannot be reactivated,' this gives both when-to-use and when-not-to-use guidance in one sentence.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description genuinely adds behavioral detail beyond annotations: the inference path where facts requires 'memories' in include, the empty-list behavior for hypotheses/rules, and the 15/10 caps. However, it does not describe the return object's structure in depth or error conditions. With annotations carrying the safety profile, a 3 is appropriate – useful additions but not fully rich behavioral 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?

Front-loaded with the core purpose, then organized as bullets per module, a Returns block, and an Args block. Every line carries needed information for a 6-param, multi-module tool; no repetition of annotation fields.

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 6-parameter tool with an output schema present, the description is complete enough: it explains module semantics, the include-based inference dependency, time-window scoping, and the alternatives. Output structure is summarized even though the output schema already covers it, so nothing an agent needs to call correctly 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?

With 0% schema description coverage, the description carries the full burden and does document all 6 parameters: topic, entity_id, include (subset of four modules with default all), and time_range/since/until scoped to the memories module only. That is meaningful semantic value beyond the bare param names. Minor gap: since/until format details ('ISO-8601') are thin and include's array item type is undocumented beyond the enumerated values.

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 verb ('Get what NEXUS has stored'), the resource (memories, facts, hypotheses, rules), the return shape (one structured object), and the read-only scope. It also names the sibling tools (retrieve_memories, get_facts_by_entity, list_hypotheses) to route away from them, so an agent can distinguish it 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?

Explicitly states the condition that selects this tool ('one read-only call' spanning multiple kinds) and the alternatives ('For a single kind of data, use retrieve_memories, get_facts_by_entity or list_hypotheses instead'). It also documents the include/entity_id dependency that changes fact behavior, giving the agent concrete invocation 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?

Goes well beyond annotations, enumerating the full side-effect chain: marks the step done/failed, adds progress_delta capped at 1.0, finalizes the plan, stores the result as an episode in memory, re-evaluates the goal, and may mark the goal achieved. This also corroborates idempotentHint=false and destructiveHint=false with concrete mutation semantics.

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

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

Front-loads the core action in the first sentence and clearly separates behavior from an Args block, so structure is strong. The behavioral paragraph is dense and long, but nearly every clause conveys distinct, load-bearing consequence information rather than filler.

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

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

For a mutation tool with no output schema, it still tells the agent what the response contains ('reports the stored progress and any recalculation') and describes preconditions and cascading effects. Nothing material needed to invoke it correctly 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?

With 0% schema description coverage, the description fully compensates by documenting all four parameters: step_id (step UUID source), result (what was done/outcome), success (pass/fail), and progress_delta (0.0-1.0 with the 0 = unchanged behavior spelled out). The progress_delta semantics in particular add meaning the bare schema lacks.

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

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

States a specific verb and resource ('Report the outcome of a plan step') and pins the source of the step to get_agent_tasks or get_pending_work, distinguishing it from read/list siblings. An agent can tell immediately what this tool consumes and what it accomplishes.

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

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

Gives clear context for invocation: the step_id must come from get_agent_tasks or get_pending_work, and it 'Fails if the step is not waiting for an agent,' which is an implicit precondition. However, it never contrasts itself with the similarly named sibling complete_task, so the agent must infer which completion tool applies.

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=false, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description usefully adds the concrete field-level effect (sets status='done' and completed_at), but says nothing about error cases such as an unknown task_id or a task already completed.

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 behavioral summary is front-loaded in the first sentence, and the Args block is terse and each line earns its place. No filler, though the docstring-style layout is slightly verbose for three parameters.

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 small mutation with no output schema, the description covers the target, the side effects and all parameter semantics, and idempotency is supplied by annotations. Only failure-mode behavior (unknown or already-completed task) is unaddressed.

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 0%, so the description must carry the load, and it does: task_id is documented as a UUID, result as an optional note, and completed_at as an optional ISO-8601 override defaulting to now. That maps cleanly to all three parameters and supplies the format detail the schema lacks.

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

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

States a specific verb and resource ('Mark a standalone task as done') and explicitly names the state change it performs (status='done', completed_at). The word 'standalone' hints at the distinction from complete_agent_task, but the sibling is never named, so the differentiation is implicit rather than explicit.

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 explicit when-to-use/when-not guidance and no named alternative, even though complete_agent_task sits right alongside this tool in the sibling list. The qualifier 'standalone task' implies scope but leaves the agent to infer that agent tasks are handled elsewhere.

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 declare the safety profile (readOnly false, idempotent false, destructive false); the description goes far beyond by enumerating concrete side effects — NEXUS root linking under hybrid, a creation episode, memory links, an event, and queued merge proposals — plus the exact return payload. This is behaviorally richer than the annotations permit alone.

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

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

Front-loaded with purpose, then disambiguation, side effects, returns, and args — every section earns its place. It is somewhat long and the Args block partially restates field names, but each entry adds semantics (especially the strategy enum values), so the size is defensible.

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 mutation tool with no output schema and 0% param description coverage, the description closes both gaps: it describes the return fields (relations_created, episode_id, event_id, memory_links_created) and all four parameters. Nothing needed to invoke it correctly 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 0%, so the description must carry the burden, and it does: name, entity_type (closed ontology, with 'unclassified' fallback), attributes, and strategy with every value ('hybrid', 'root', 'similar', 'none') individually explained. This adds meaning well beyond the bare schema names.

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

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

States a specific verb+resource ("Create a new entity in the world model") and immediately distinguishes itself from siblings by naming the alternative reuse-or-create path via relate_entities and search_entities. An agent knows exactly what this tool does versus create_entity_cognitive or update_entity.

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

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

Explicit when/when-not guidance: "Always inserts a new node; it does not check for an existing entity with the same name." It then routes the agent to alternatives (relate_entities for reuse-or-create, search_entities to check first, create_entity_cognitive for explicit links), covering both the tool and its exclusion 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?

Beyond the annotations (readOnlyHint=false, idempotentHint=false), the description discloses rich behavior: always inserts a new node, records a creation episode/memory links/event, may queue merge proposals for similar names, and is atomic ('If any explicit link targets an unknown entity, nothing is created'). These are non-obvious side effects and transactional guarantees the agent could not derive from the structured fields.

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

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

Purpose and key transactional caveat are front-loaded before the Args block, and every sentence carries information. The Args enumeration is slightly dense but earns its place given 0% schema coverage and nested objects.

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 6-param tool with nested objects and no output schema, the description covers purpose, side effects, atomicity, and per-parameter semantics adequately. The only shortfall is unexplained meaning for weight/causal_probability, but nothing critical for correct invocation 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 0%, so the description carries the full burden, and it largely succeeds: it enumerates all 6 params and spells out the strategy enum values ('hybrid'/'explicit'/'root'/'similar'/'none') with their exact wiring, plus the nested explicit_links fields (relation_type default 'related_to', direction default 'outgoing'). Minor gap: weight and causal_probability are named but not explained semantically.

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+resource+scope: create a new entity AND link it to existing entities in one call. It explicitly distinguishes itself from create_entity by explaining shared side effects ('Like create_entity, it records a creation episode...') and adding the linking capability, so an agent can route correctly among create_entity, create_relation, and relate_entities.

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 conveys the contextual split implied by 'link it to specific existing entities in the same call' and contrasts with de-duplicating behavior ('no name de-duplication'), which hints at when this differs from a merge/de-dup path. However, it never states explicit when-not conditions or names an alternative tool to use instead, leaving the choice between this and create_entity + create_relation 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 non-readOnly, non-destructive, non-idempotent behavior, and the description adds substantial context beyond them: the draft lifecycle state, priority validation rules (rejects >10 or <0), goal_type normalization into stored achievement/maintenance values, and the 404 on a missing parent. This is exactly the kind of behavioral detail annotations cannot 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?

Purpose is front-loaded, then a clean Args block with one entry per parameter. The goal_type entry is slightly dense with the value/storage mapping repeated, but every sentence adds usable information and there is no filler.

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

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

For a mutation tool with an output schema already covering return values, the description supplies everything else an agent needs: creation semantics, lifecycle, validation constraints, type normalization, and error behavior. Nothing material 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 0%, so the description carries the full burden and does so: it documents all five parameters, including the priority range and default, the accepted goal_type values with their storage mappings, and the semantics and failure mode of parent_goal_id. Only `name`/`description` are lightly glossed, but their meaning is self-evident.

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

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

States a specific verb and resource ('Create a goal') and immediately frames the lifecycle ('start in draft status'), which lets an agent distinguish it from get_goal/list_goals. It also names `activate_goal` as the follow-up sibling, so the boundary 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?

It gives a concrete when-this-matters condition: new goals are not worked on until activated via `activate_goal`, which routes the agent to the next tool. It doesn't explicitly compare against create_task or explain when a goal is the right entity versus a task, so it falls short of full alternative coverage.

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?

Far exceeds the annotations (which only give readOnly/destructive/idempotent/openWorld hints). It discloses that 'same_as' opens a pending merge proposal rather than a relation, enumerates four rejection cases (missing entity, duplicate, self-relation, cycle), and explains contradiction-opening behavior for single-valued types.

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

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

Front-loaded purpose, then a scannable Behavior bullet list, then Args. Dense and nearly waste-free, though the Args block partially restates schema field names, adding a little 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 6-parameter mutation tool with no output schema, the description covers side effects, error conditions, and the merge-proposal return id, leaving nothing an agent needs to call it correctly unspecified.

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 0%, so the description must carry the load, and it does: source/target are UUIDs, relation_type comes from a closed ontology, weight and causal_probability defaults are given, and the properties key restriction ('only weight and causal_probability, anything else errors') is fully specified.

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

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

States a specific verb and resource ('Create a directed relation between two existing entities in the world model') and immediately distinguishes itself from the sibling relate_entities by noting the UUID-based vs name-based referencing.

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

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

Explicitly routes the agent: use relate_entities to relate by name, use 'related_to' plus store_fact when no ontology type fits, and uses resolve_contradiction for the single-valued conflict case. Alternatives and conditions are named, not implied.

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 safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false), so the bar is lower. The description still adds substantive behavior: the rule is persisted as active in NEXUS's rule registry, is retrievable via list_rules, and its confidence decays over time unless re-verified — none of which the annotations 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?

Front-loaded with the concept and lifecycle, then a clean Args block; each line earns its place. It is slightly longer than strictly needed, but there is no filler 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 5-parameter mutation tool with no output schema, the description covers what the tool does, where the result lives, and how it ages. It omits any mention of authorization or failure modes, but nothing essential for calling it correctly 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 0%, so the description carries the full burden, and it does: it explains each of the five parameters semantically (condition = when the rule applies, action = the conclusion when it holds, confidence as a weight in [0.0, 1.0]). The only blemish is that it says domain defaults to 'general' while the schema declares a null default.

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

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

States a specific verb (Store) and a precisely defined resource: 'a standing rule: a condition and the conclusion or action that applies when it holds.' The definitional gloss (condition + action) distinguishes it from sibling writers like store_fact and store_procedure, and it explicitly ties the result to list_rules and affirm_rule.

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 examples of when this applies ('a project constraint or a convention') and points to affirm_rule for re-verification, which is real routing guidance. It stops short of explicitly saying when to prefer create_rule over store_fact or store_procedure, so there is no true when-not clause.

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=false, destructiveHint=false, idempotentHint=false, and openWorldHint=false, so the safety profile is largely covered. The description adds genuine nuance: goal_id is a 'weak link' that keeps the task standalone, and created_at is an override for backfilling. These are helpful behavioral details beyond the annotations, though most of the text is parameter explanation.

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

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

Purpose is front-loaded in the first line, followed by an organized Args list where each entry earns its place given the empty schema coverage. The list format is functional rather than elegant, but nothing is wasted.

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 9-param, single-required mutation tool with no output schema, the description documents every input thoroughly, including defaults, formats, and semantics. Return behavior need not be explained since no output schema exists, so it is effectively complete for the calling decision.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description fully compensates, documenting all 9 params: the priority 0.0–1.0 range with default 0.5, source enum values ('agent'/'user'/'system'), ISO-8601 format with an example ('2026-07-05T09:00:00'), and the required status of title. This adds substantial meaning the bare schema lacks.

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

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

States a specific verb+resource ('Create a standalone task') and immediately differentiates scope with 'a unit of work NOT part of any goal plan,' which cleanly separates it from goal-oriented siblings like create_goal and submit_goal_plan. An agent can identify its role 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 'NOT part of any goal plan' clause implies when to prefer this over create_goal, giving useful scope-based guidance. However, it names no alternative tool explicitly and gives no when-not conditions, so usage must be inferred.

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, idempotentHint=true and readOnlyHint=false, so the safety profile is largely covered. The description still adds substantial context beyond that: the surviving entity inherits relations/facts/episodes/aliases, merges are reversible, and it fails on non-pending proposals. The reversibility claim does qualify the destructive hint rather than contradict it.

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

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

Front-loaded with the core action before the argument breakdown, and every section earns its place. It is dense with nested parentheticals, which slightly taxes readability but does not include filler.

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

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

For a destructive, no-output-schema mutation tool, the description covers the failure condition, reversibility, default behaviors, and downstream effects of each decision. Nothing an agent needs to invoke it correctly 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 0%, so the description carries the full burden, and it documents all five parameters: candidate_id, the three decision values with meanings, conservar with its default rule, por_usuario's default and recorded meaning, and razon for audit. This fully compensates for the empty schema.

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

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

States a specific verb and resource ('Decide an entity-merge proposal') and immediately names the sources it consumes (get_merge_doubts, duda_de_fusion, same_as relation). An agent can distinguish this from siblings like ratify_relation or resolve_contradiction without opening any schema.

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

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

Explains where proposals originate, when the call fails ('no longer pending'), and the exact consequence of each decision option, including that 'distintas' is never proposed again and 'posponer' recurs in 3 days up to a limit. This is explicit when/when-not guidance tied to the enum choices.

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 destructive and idempotent, but the description adds critical context: permanent deletion with no undo/trash, downstream effect on match_procedures, return value, and unknown-UUID error behavior. It enhances rather than contradicts 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?

Front-loads the destructive nature and irreversible consequence, then provides alternatives and parameter guidance. Every sentence 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?

No output schema exists, but the description includes the return shape ({"deleted": true}) and the not-found error case. Combined with annotations and clear parameter provenance, an agent has everything needed to call this 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 0%, so the description carries the burden for the single proc_id parameter. It specifies the UUID format and where to obtain it (get_procedure, match_procedures, list_procedures), which is meaningful beyond the bare schema.

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

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

States a specific verb and resource ("Permanently delete one stored procedure and its steps") and clearly distinguishes the action from alternatives. The agent can tell exactly what this tool does.

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

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

Explicitly states intended use ("procedures that are wrong or obsolete") and names alternatives with conditions: update_procedure for fixes, record_procedure_usage with success=False for intermittent failures, and get_procedure for inspection. This is strong routing 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 destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds the permanence framing ('Cannot be undone'), but says nothing about cascading effects (subtasks, comments, relations) or permission requirements, which are the real unknowns for a destructive 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?

Two short sentences plus a minimal args block; the destructive nature and the argument are front-loaded with zero filler.

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

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

For a single-parameter destructive tool with no output schema and annotations covering destructiveness, the essentials are present. It is still thin on side effects and error/permission behavior, which matters when deletion is irreversible.

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 0% and the schema only says the field is a string, so the description must compensate. It does by specifying that task_id is a UUID of the task to delete, which is meaningful format information 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?

States a specific verb (delete) and resource (task), and adds the 'standalone' qualifier that separates it from procedure/entity deletion and from task-completion siblings. It stops short of naming an alternative tool, so it is clear but not fully differentiated from siblings like complete_task or update_task.

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 'standalone' implies a constraint on what may be deleted, which is implied usage guidance. However, it never says when to delete versus complete/update a task, nor what happens if the task is not standalone.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds real context beyond them: the relation is retained in history and disappears only from current state, the call fails if already closed or if valid_until precedes the start date, and a source citation is mandatory. Minor tension: idempotentHint=true while a repeat call on a closed relation fails, which the description does not reconcile.

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

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

Front-loads the action, then the persistence consequence, then failure conditions, then the alternative tool, then parameters. No sentence is filler and the routing advice is placed where an agent will read it before acting.

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 takes responsibility for describing the outcome (historical retention vs current state), the failure modes, and the required evidence – everything needed to invoke correctly. Only the ambiguous idempotency behavior remains unaddressed.

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 0%, so the description must carry all three parameters – and it does: relation_id's provenance (query_world_model or get_entity_relations), valid_until's ISO 8601 format and start-date constraint, and evidence_ref's accepted forms (URL, person, document, episode id).

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

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

States a specific verb+resource plus the mechanism ('setting its end date') and the semantic effect (relation becomes no-longer-true). It is clearly distinguishable from create_relation, relate_entities, and ratify_relation.

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

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

Explicitly routes the agent elsewhere for the tricky case: for works_for/reports_to/located_in changes to a new target, use relate_entities with supersede_previous=True instead. It also states the two conditions under which this tool fails, so the agent can pre-validate.

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=false, and the description reinforces this with a concrete explanation of re-application and evidence accumulation. It also discloses the exact scoring algorithm, status transitions, version increment, and 404 behavior—rich context well 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 front-loaded with purpose, then scoring rules, then args, which is a logical structure. It is slightly long because the scoring algorithm is spelled out step by step, but that detail earns its place by clarifying non-obvious behavior.

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 mutation tool with no output schema, the description covers what is written and the 404 case, so an agent knows the side effects. It does not state what the call returns (e.g., the updated hypothesis or a status object), which is a minor remaining 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?

With 0% schema description coverage, the description fully compensates: it identifies hypothesis_id as a UUID and documents the nested evidence object with allowed evidence_type values, defaults, score range, and optional details. This is more than the bare schema 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?

States a specific verb (re-score) and resource (hypothesis) with clear scope: re-score against all stored evidence, optionally adding one new item, and save. It also distinguishes itself from the sibling list_hypotheses by pointing there only for ID lookup.

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 clear when to call it (to re-score a hypothesis, with or without new evidence) and references list_hypotheses for obtaining the required ID. It stops short of explicitly naming when not to use it or listing alternative scoring paths, but the context is 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?

The description discloses a genuine side effect that annotations alone would leave opaque: NEXUS re-checks maintenance steps and may refresh, resolve, or cancel stale ones before returning. That explains the readOnlyHint=false flag and is useful context. Beyond that, it doesn't cover permissions or failure modes, so with annotations carrying the safety profile this is a solid but not rich disclosure.

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 paragraphs, front-loaded with the purpose and ordering, then routing, then the side effect. Every sentence carries information the agent needs; nothing restates the name or 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?

With no parameters and no output schema, the description must carry the full burden, and it does: it enumerates returned fields, states scope limits, names the completion sibling, and warns about the pre-return maintenance pass. An agent has enough to call and interpret this 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?

Zero parameters, so there is nothing to disambiguate; the description instead enumerates return fields (step_id, instruction, context, expected effect, estimated progress, goal). Informative, but per the zero-param baseline this sits at the standard level rather than above it.

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

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

States a specific verb and resource ('List the pending plan steps ... queued for an agent'), plus the ordering rule (goal priority, then step order) and the scope restriction (only each active goal's current plan). This is clearly distinguishable from get_pending_work and complete_agent_task, which the description names.

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

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

Explicitly routes the agent: outcomes go to complete_agent_task, and standalone tasks belong to get_pending_work. Combined with the 'only current plan' scope limit, the agent can decide when this tool is and is not the right call without opening any schema.

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 the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds substantial context beyond them: scores are computed live rather than cached, null means no data, and recommended_strategy is advisory only with strategy_applied always false. That last point is exactly the kind of side-effect clarification an agent cannot get from 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?

Purpose is front-loaded in the first sentence, then return semantics are grouped by field, then signal sources, then interpretation. Every sentence carries information an agent needs; nothing is filler or restated.

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

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

There is no output schema, so the description carries full burden for return values and it delivers: direction and range for each score, null semantics, the advisory nature of recommended_strategy, the structure of `signals`, and the category list the signals cover. An agent can interpret the response without any other source.

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 takes zero parameters, so the schema baseline of 4 applies and there is no parameter ambiguity for the description to resolve. No further parameter explanation is needed or given.

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

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

States a specific verb and resource ('get a read-only health report for the user's knowledge base') plus a key qualifier: computed live from the user's own data rather than from static stats. It does not differentiate itself from nearby siblings such as get_world_model_stats or query_world_model, so an agent must infer which diagnostic surface to pick.

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

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

Usage is implied rather than stated: the closing sentence ('A high uncertainty or drift score means recalled information is less reliable than usual') hints at when a health check matters, but there is no explicit when-to-use, when-not-to-use, or named alternative. An agent gets a rationale but no routing rule.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds genuinely new behavior: expired entries are filtered out, ordering is priority then most-recent-first, and unknown/empty sessions return [] rather than erroring. Only gap is that it restates 'Read-only' which annotations already 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?

Front-loaded with purpose, then return shape, then usage, then args — a sensible order. Slightly redundant in restating 'Read-only' after the annotations and in the multi-line arg block, but no sentence is wasted at the level of 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?

No output schema exists, and the description compensates by describing the returned fields, expiry filtering, ordering, and the empty-result case. Combined with the usage routing and the session_id disambiguation, an agent has everything needed to call this correctly on the first try.

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 0% and the only parameter is undocumented in the schema, so the description must carry it — and it does: session_id is the application-level NEXUS id used with push_context, explicitly NOT the MCP transport session. That disambiguation is exactly the failure mode an agent would otherwise hit.

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

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

States a specific verb and resource ('Read a session's working memory') and immediately defines the resource as the short-lived key/value entries written by push_context. That definition, plus the explicit contrast with durable knowledge in retrieve_memories/cognitive_query, separates it cleanly from the many memory-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?

Explicit positive case ('recover scratch state within the same piece of work, e.g. what you were in the middle of'), explicit negative case (durable knowledge is not here; use retrieve_memories or cognitive_query), and a routing note that retrieve_memories also returns these entries with the same session_id. When-to-use, when-not, and alternatives are all present.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered by structured data; the description still adds real value beyond that: an unknown UUID returns a not-found error, names are not accepted as input, and the record deliberately excludes relations, neighbors and episodes. Minor redundancy in restating 'Read-only' costs it the top mark, but the error behavior and scope boundaries are genuinely useful disclosures.

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

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

Front-loaded with the core action and return payload, then usage, then alternatives, then the single argument. Every sentence carries a distinct fact; the Args block is not padding because the schema provides no parameter description at all.

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

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

There is no output schema, but the description compensates by enumerating the returned fields, and it covers the error path (not-found) and the scope boundaries. For a single-parameter read tool, an agent has everything needed to call it correctly and interpret the result.

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 0% -- the schema only says 'Entity Id' as a bare string -- so the description carries the full burden, and it does: it specifies the format (UUID), points to a concrete source ('the `id` returned by search_entities'), and adds a negative constraint ('Names are not accepted') that prevents a common misfire. This is exactly the compensation a low-coverage schema needs.

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

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

States a specific verb and resource -- 'Read one entity's own record by UUID' -- and immediately enumerates what is returned (type, attributes, aliases, version, epistemic status, timestamps). The 'own record' phrasing and the explicit exclusion of relations/neighbors/episodes distinguish it cleanly from get_entity_graph_context, get_entity_relations and get_entity_episodes in the sibling list.

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

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

Gives the exact precondition ('when you already hold an entity UUID'), names where such a UUID comes from (search_entities, a relation, an episode), and routes to three named alternatives for the cases this tool does not cover. It also states that search_entities is the tool for resolving a name to a UUID, closing the obvious loop.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is fully covered without description help. The description does add genuinely new behavioral context - results are ordered 'most recent first' - which is not derivable from annotations or schema, but it omits pagination/cursor behavior and result 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?

Purpose is front-loaded in the first sentence, followed by tightly scoped argument notes with no redundant or filler text. Every sentence adds information an agent could not infer from the schema alone.

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 two-parameter, read-only list tool with no output schema, the description covers purpose, ordering, and parameter bounds adequately. It could say a bit more about what an 'episode' contains or how to page beyond the limit, but nothing essential to correct invocation 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 0% (only bare titles), so the description carries the full burden and largely does so: it explains entity_id is a UUID of the entity and that limit is a maximum bounded to 1-200. It does not mention the default value of 20, which is the only remaining gap.

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

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

States a specific verb and resource ('List episodes') plus scope ('in which the given entity participates'), which an agent can clearly distinguish from siblings like retrieve_memories or get_entity_relations. It doesn't explicitly name a sibling to contrast against, 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?

Usage is implied by the name and by the phrase 'in which the given entity participates' - it's evident this is the entity-scoped episode lookup. However, there is no explicit when-to-use guidance versus related read tools (get_entity, get_entity_graph_context, retrieve_memories) and no stated prerequisites such as the entity needing to exist.

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 safety profile is covered. The description usefully discloses the composite shape of the result but adds no auth, rate-limit, or pagination/truncation context.

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

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

The purpose sentence is front-loaded and enumerates the return payload precisely, followed by a compact docstring-style Args block. No wasted sentences, though the Args section is slightly redundant with a 2-param 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?

With no output schema, the description does the work of describing what comes back (relations, neighbors, episodes), which is what an agent needs to decide relevance. It is complete enough for a read-only composite fetch, missing only guidance on how it relates to the single-purpose siblings.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description carries the param burden, and it does: entity_id is specified as a UUID (beyond the schema's bare 'string') and episode_limit gets a range (0-50), default behavior, and the meaning of 0. It compensates well for the coverage gap, though the arg formatting is terse.

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 composite resource set: the entity, its incoming and outgoing direct relations, neighbor entities, and recent episodes. It implicitly distinguishes itself from the narrower siblings (get_entity, get_entity_relations, get_entity_neighbors, get_entity_episodes) via 'in one call' but never names 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?

Usage is only implied by 'in one call', which suggests this is a bundle alternative to the separate get_entity_* tools, but there is no explicit when-to-use, when-not, or named alternative. An agent must infer the tradeoff itself.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered, yet the description still adds substantive behavior: results are de-duplicated, relation provenance is deliberately omitted, and an entity with no relations returns []. It even enumerates the returned record fields (id, type, attributes, aliases), which matters since no output schema exists. Minor gap: nothing about volume, truncation, or ordering of the neighbor list.

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

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

Front-loaded with the traversal semantics, then usage routing, then the argument hint. Three short blocks, no restated boilerplate, and every sentence carries either scope, a routing alternative, or argument guidance.

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, annotation-covered, no-output-schema tool, the description covers what it returns, its edge case (empty list), the de-duplication caveat, and the alternatives. An agent has everything needed to decide and 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 coverage is 0% (entity_id has no description), so the description must compensate and largely does: it specifies the format (UUID) and the provenance of the value (the `id` returned by search_entities). It stops short of stating what happens with an unknown or non-UUID id.

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

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

States a specific verb and resource ("List the entities directly connected to an entity") plus the exact traversal semantics: one hop, any relation, either direction, including ended relations. It also explicitly disclaims what it does not do (no relation types returned), which lets an agent distinguish it from get_entity_relations and get_entity_graph_context without opening a 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 second paragraph routes the agent by need: get_entity_relations when relation types/direction/validity dates matter, get_entity_graph_context for a combined relations+neighbors+episodes call, and query_world_model for current state only. Each named alternative comes with the condition that selects it, leaving nothing 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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond them: results include stale/no-longer-current relations and a structural root link, which tells the agent the payload is broader than just live edges. Return shape/pagination is not described, but no output schema exists to absorb 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?

Front-loads the scope and the distinguishing detail (historical relations, NEXUS link), then gives the alternative in one clause and the argument definition. No filler sentences.

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 tool with full annotation coverage and no output schema, the description tells the agent exactly what set of relations comes back and when to prefer the sibling. Nothing needed to call it correctly 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 0% and the lone parameter is documented only as a plain string, so the description's 'UUID of the entity' adds real semantic value about the identifier format. It is a single required parameter, so there is little else to clarify.

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

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

States a specific verb (return) and resource (every relation attached to an entity), and precisely defines scope: outgoing and incoming, including superseded relations and the NEXUS root link. An agent can distinguish it from get_entity_neighbors or query_world_model without opening any schema.

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

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

Explicitly routes the agent: this tool for the full relation history, 'For current state only, use query_world_model.' Names the alternative and the condition that selects it, so nothing 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 declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: a hard cap of 50 results and confidence-descending ordering. It omits what happens when truncation occurs or how to fetch more, which keeps it from a 5.

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

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

Front-loads the key return semantics in the first sentence and follows with a compact Args block. No filler; the only mild redundancy is restating entity_id in the args list, though it usefully carries the UUID format detail.

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 tool with full annotation coverage and no output schema, the description covers scope, result cap, ordering, and parameter format. The main gap is truncation/pagination behavior when the 50-result cap is hit.

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 0% and the only param is a bare string, but the description compensates by specifying the expected format ("UUID of the entity"), which the schema does not convey. With a single fully-described parameter, this is adequate.

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

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

States a specific verb+resource ("Get semantic facts") plus the scope ("in which an entity is the subject or the object"), which is more precise than the title. It does not name or distinguish itself from plausible siblings like get_entity_relations or get_entity_episodes, so it stops short of full sibling differentiation.

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

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

The description says what is returned but never states when to choose this tool over alternatives such as get_entity_relations, get_entity_neighbors, or query_world_model. No prerequisites, exclusions, or usage context are given; the agent must infer usage from the name.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety bar is low; the description still adds real value by naming the not-found error for an unknown UUID and by flagging that close_goal is irreversible. It does not cover rate limits or pagination, which is a minor gap for a single-object read.

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

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

Front-loaded with the core action, and the routing hints follow logically. The long enumeration of returned fields partly duplicates the output schema, which is mild redundancy, but the fields carry semantic detail (progress 0-1, status examples) that earns most of its space.

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, single-object read with an output schema and full annotations, the description covers action, scope, parameter origin, error behavior, and sibling distinctions. Nothing an agent needs to call it correctly 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 0%, so the description must carry the burden, and it does: goal_id is described as the goal's UUID, with a pointer to where to obtain it (`id` from list_goals or create_goal). It stops short of stating format constraints or validation rules, so not a full 5.

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

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

States a specific verb and resource ('Read one goal in full by UUID') and immediately enumerates the fields returned, so the agent knows exactly what it gets. It is clearly distinguished from list_goals, which is described as returning only goal UUIDs.

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

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

Explicitly routes the agent: list_goals for UUIDs, get_agent_tasks for the queued steps of the plan, and notes that update_goal/close_goal act on target_state and success_condition. It gives clear context for selection but stops short of an explicit 'use this when you need X instead of Y' rule for every sibling.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description confirms 'Read-only.' Beyond that it discloses the payload shape (evidencia with type, aliases, relations, facts; reason nullable) and the important behavioral note that 'distintas' is permanent. It does not cover ordering or how pendientes is computed, which is minor.

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

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

Front-loads purpose, then differentiation, then decision semantics, then args and return shape — a sensible order with no filler sentences. The decision-vocabulary block is slightly long but each label earns its place by preventing misuse.

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 supplies the return shape (dudas list with id, entity_a, entity_b, reason, evidencia plus pendientes) and the full read-decide loop. Nothing an agent needs to call this and act on the result 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 0%, so the description must carry the parameter: it does, giving the meaning and the 1-20 bound for limit. The schema default of 5 is not mentioned, and no behavior is described for out-of-range values, keeping it short of a 5.

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

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

States a specific verb and resource ('return pairs of entities that may be the same and that NEXUS could not decide') and immediately names the sibling it is not (get_next_question), including the distinguishing property por_usuario=False. An agent can pick this over the sibling without opening either schema.

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

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

Explicitly says these doubts are for the agent to decide rather than to ask the user, points to retrieve_memories for context, and routes decisions to decide_merge_proposal with a precise semantic mapping of fusionar/distintas/posponer. When-to-use and what-to-do-next are both covered.

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 safety is covered; the description nonetheless restates 'Read-only' (redundant) and adds genuinely useful context: the null case, and that queued count excludes postponed questions. It stops short of explaining side effects on the queue or what 'evidencia' contains.

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

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

Front-loaded with the core behavior and the null case in the first sentence, with the decision linkage and return shape following. The 'Read-only' line duplicates the readOnlyHint annotation and is the one sentence that doesn't fully earn 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 responsibly documents the return shape ({pregunta: {...} | null, pendientes}) and the meaning of pendientes. It leaves the internal fields (entity_a, entity_b, reason, evidencia) uninterpreted, which is a minor gap for an agent that must act on them.

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?

Zero parameters, so the baseline of 4 applies; there is nothing for the description to disambiguate. The description correctly focuses its effort on the return payload instead of inventing parameter guidance.

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

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

States a specific verb ('Return') and resource ('the next pending entity-merge doubt'), including the null-case behavior, and anchors it to a sibling ('same shape as one item of get_merge_doubts'). An agent can distinguish it from the list-shaped sibling and from decide_merge_proposal without opening a 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?

It names the follow-up action explicitly ('The decision is applied with decide_merge_proposal') and clarifies that 'pendientes' excludes postponed questions. It lacks an explicit 'use this instead of get_merge_doubts when...' exclusion, but the get/pending framing implies the queue-draining usage.

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 readOnlyHint, idempotentHint, destructiveHint and openWorldHint, so the safety profile is settled. The description adds two things annotations cannot: ordered (chronological) results and an access-scope constraint limiting output to messages the caller sent or received. It stops short of covering pagination or result size limits.

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

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

Two short sentences front-load the purpose and ordering before the Args block. The Args block largely restates the schema field, which is mild redundancy, but the sourcing detail makes it earn 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 single-parameter read tool with rich annotations and no output schema, the description covers purpose, ordering, and visibility scope adequately. Return shape need not be explained, though the absence of any note about result limits or empty-thread behavior leaves a small 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 0%, so the description carries the full burden and does so meaningfully: it identifies thread_id as a Thread UUID and tells the agent where to find it (present in every sent and received message). That is real operational guidance beyond the bare string type, though no format example or failure mode is given.

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

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

States a specific verb and resource ('Get a conversation between agents') plus the distinguishing traits of chronological ordering and caller-scoped visibility. It is clearly separable from the sibling read_messages, though it does not name that sibling explicitly.

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

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

Usage is implied rather than stated: the note that thread_id is 'included in every sent and received message' tells the agent where to source the identifier, which hints at when this tool applies. However, it never says when to prefer this over read_messages or send_message, and gives no 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, non-destructive and closed-world, so safety is covered structurally. The description adds genuinely new context: the setting defaults to off and why (incoming messages are foreign text entering the agent's context), which matters for interpreting the result. It stops short of describing the response envelope.

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

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

Two short sentences, front-loaded with the return value, then the default and its rationale. No filler, and the sibling pointer is placed last where it is most useful.

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-param read with rich annotations and no output schema, the description covers what is returned, the default state, and where to change it. It leaves slight ambiguity about the exact response shape (whether only `accept_from_other_users` is returned or additional preference fields accompany 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?

Zero parameters, so there is nothing to disambiguate; baseline is 4. The description correctly frames the call as scoped to 'this user's agents' with no identifiers 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?

States a specific verb and resource (return the `accept_from_other_users` messaging preference) and names the exact flag returned. It also implicitly separates itself from the setter sibling `messaging_preferences`, so an agent can pick the right tool without opening a 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?

Points at the alternative that matters — `messaging_preferences` is the tool that changes this value — which gives clear read-vs-write routing. It does not spell out explicit when-not conditions (e.g. whose preferences can be read), so it falls just 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 cover readOnly/idempotent, yet the description adds real behavioral context beyond them: the priority ordering of question sources, the fact that NEXUS pre-attempted resolution, the one-at-a-time design constraint, and which tool consumes the result. It even clarifies why merge doubts are excluded.

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

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

Front-loaded with the core purpose and the priority ordering immediately after. Slightly padded by the 'Read-only: fetching a question does not change it' sentence, which restates the readOnlyHint annotation and is the one sentence that does not fully earn 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 return-shape burden and does so precisely, describing the nullable pregunta object, its fields, and the pendientes counters. An agent has everything needed to call it and interpret the 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 takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate on the input side. It does add value by naming the returned fields (texto, datos, respuestas, pendientes), though that is more return-shape than parameter semantics.

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

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

States a specific verb and resource ('Return the next pending question NEXUS has for the user') with an explicit null case. It also names the sibling it is not (get_merge_doubts) and explains the two question sources, so an agent can distinguish it from get_merge_question and get_next_question-adjacent tools without opening a schema.

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

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

Explicitly states when to use it (one question at a time, after NEXUS has already attempted automatic resolution) and when not to (entity-merge doubts, routed to get_merge_doubts). It also names the follow-on tool, answer_question, for applying answers or postponements.

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 the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds meaningful context beyond them: that learned types/aliases originate from stored data and that 'dudas' entries are still awaiting a decision, implying a dynamic, evolving vocabulary.

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

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

Front-loaded with purpose, then scope, then return shape. Information-dense and mostly waste-free, though the inline enumeration of the return object (core/extensions/core_aliases/dudas plus relation properties) is long and slightly run-on for a description body.

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 burden of explaining return values, and it does so in useful detail (core vs extensions, aliases, dudas, and the per-type properties like inverse/functional_in_time/temporal/transitive). It stops short of showing the exact dudas entry shape, but an agent has enough to act.

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 takes zero parameters, so the baseline is 4. There is nothing further the description could add about inputs, and it correctly spends no space on them.

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

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

States a specific verb and resource ('Return the world-model vocabulary') and immediately scopes it to core entity/relation types plus account-specific learned types and aliases. This is clearly distinguishable from siblings like query_world_model, get_world_model_stats, or list_entities.

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 how the returned vocabulary is consumed downstream: learned relation types are usable in process_observation triples while relate_entities accepts core types only. That effectively tells the agent when the output matters, though it never states an explicit 'call this before relate_entities' trigger or when-not-to-use condition.

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

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

Annotations already declare readOnly, idempotent, non-destructive, non-open-world, so the safety profile is covered. The description still adds real behavioral detail beyond that: pagination semantics, the fact that oversized results fail rather than truncate, and the meaning of the 'system' source. It does not describe ordering guarantees for plan_tasks or concurrency, keeping it from a 5.

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

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

The definition is front-loaded with the two result categories, then tool relationships, then totals, then args, which is a sensible reading order and every section earns its place. It is longer than strictly minimal, with some redundancy between the bullet list and the prose, but nothing is wasted.

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

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

There is no output schema, and the description compensates thoroughly by enumerating summary row fields (id, title, status, priority, source, tags, dates, description preview), the totals keys (standalone_total, standalone_by_source, has_more), and the optional 'preguntas' element. An agent has everything needed to call it and interpret the 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?

Schema description coverage is 0%, so the description must carry the full burden, and it does: limit (default 25, max 100, max 10 with full=True), offset (skip count for next page), and full (full objects vs summaries, plus the failure-on-oversize caveat). All three parameters gain constraints and behavior absent from 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 states a specific verb (list) and resource (open work) and immediately splits it into two concrete categories, standalone_tasks and plan_tasks, with the statuses each covers. This lets an agent distinguish it from siblings like list_tasks, get_task, and get_agent_tasks without opening any schema.

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

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

It clearly maps consumption of the output to sibling tools: plan steps via complete_agent_task, standalone tasks via update_task/complete_task, single-task detail via get_task, and pending questions via answer_question. That is strong contextual routing, though it never explicitly states when to prefer this over list_tasks or get_agent_tasks, so it stops short of full when/when-not 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 read-only, idempotent, closed-world safety, so the description only needs added context — and it supplies ordering (by goal priority), empty-list semantics, the absence of a step limit, and the fact that step_schema is returned for the submitted plan. No permissions or rate-limit detail, but the safety profile is already 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?

The filter criterion is front-loaded in the first clause, followed by ordering, then return contents. The field enumeration is a touch long but earns its place because no output schema exists to document the return shape.

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 must describe the return shape, and it does: item fields, ordering, and the empty-list case. For a zero-parameter read tool with full annotation coverage, nothing an agent needs to call it correctly 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?

Zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. It correctly implies a no-argument call.

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

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

States a specific verb (list) and resource (planning requests) plus the exact filter: active goals with no live plan, whether never submitted or finished. An agent can distinguish this from list_goals or get_pending_work without opening a schema.

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

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

Explicitly routes the agent to the successor tool ("a plan can be written for them and submitted with submit_goal_plan") and describes the trigger condition (no live plan). It does not name an alternative list tool to avoid, so it stops short of full when/when-not 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 readOnly, idempotent, non-destructive, closed-world, so the safety burden is light; the description still adds useful behavior by specifying the not-found error for an unknown UUID and the full shape of what is returned. Missing only things like permission requirements, which are unlikely for a read.

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

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

Front-loaded with purpose and return shape, then routing guidance, then args. Every sentence carries information, though the enumerated field list and separate Args block make it slightly longer than strictly necessary.

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 with no output schema, the definition covers purpose, returned contents, error behavior, and sibling alternatives — everything needed 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 coverage is 0%, so the description must carry the parameter meaning — it does, defining proc_id as the procedure UUID and pointing to the `id` from match_procedures or list_procedures as its source, which is more than the bare string schema 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?

States a specific verb and resource ('Read one stored procedure by UUID') and enumerates what is returned (name, description, ordered steps, tags, success rate, usage count, timestamps), which also distinguishes it from match_procedures and list_procedures.

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

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

Explicitly says it is for following or reviewing an already-identified procedure and names the sibling routing: match_procedures to find one for a task, list_procedures to enumerate, record_procedure_usage to log an outcome. When-to-use and alternatives are both covered.

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

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

Beyond annotations, it discloses a real side effect: on OAuth connections the call issues a hooks credential embedded in the script, and that credential cannot be shown again. It also explains the plain token case, the `steps` indicator, and exactly what running the installer would do. This is precisely the kind of behavioral context annotations do not cover.

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 front-loads the purpose and then adds necessary detail about side effects and client differences. Some sentences could be tightened, but the density is justified by the complexity of the installer and credential behavior.

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

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

There is no output schema and only two parameters, but the description covers the kit contents, installation behavior, credential side effect, client-specific differences, and the `steps` output. An agent has enough information to decide whether to call it and how to interpret the result.

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 0%, so the description must compensate, and it does. The Args section explains `formato` values (`script` vs `files`), defaults, and the Cursor caveat, plus `client` values and the behavioral difference for Cursor's hook set. This fully documents both parameters beyond the bare 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 states a specific verb and resource: it returns the setup kit for local agents, and it enumerates exactly what the kit contains. It also scopes the tool by naming the applicable clients and excluding chat clients, so an agent can identify it without ambiguity.

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

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

It explicitly states when the kit applies (Claude Code and Cursor agents on the user's own machine) and when it does not (chat clients such as Claude web, desktop, or ChatGPT). It also clarifies that calling only returns the kit and that installation is the user's decision, which is exactly the guidance needed before invoking it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so safety is covered. The description adds genuine behavioral value by disclosing the breadth of the payload (dates, result, tags, full comment thread) that the annotations do not convey, which matters since there is no output schema.

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 return-value sentence is front-loaded and information-dense; the 'Args:' block repeats the single parameter but earns some place given 0% schema description coverage. Slight redundancy keeps it from a 5.

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 does the work of listing the returned fields, which makes it largely complete for a single-fetch tool. The one ambiguity is what 'standalone' excludes (agent-owned tasks), which is left for the agent to infer.

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 0%, so the schema alone does not document task_id. The description partially compensates by stating it is the 'UUID of the task', adding format meaning, but gives no guidance on where to obtain the id or what happens on an unknown id.

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

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

States a specific verb+resource ('Get a single standalone task') and enumerates the detail returned (dates, result, tags, comment thread). The word 'single' and 'standalone' distinguishes it from list_tasks and get_agent_tasks, though it never names those siblings explicitly.

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

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

Usage is only implied: the contrast between 'a single standalone task' and the sibling list/agent-task tools suggests when to reach for it, but there is no explicit when-to-use or when-not-to-use statement. No prerequisites or alternatives are named.

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, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description's 'Read-only.' merely repeats that and adds no behavioral context beyond the annotations, such as rate limits, auth needs, or side effects. The metric list adds scope but not behavioral traits.

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 the purpose and a detailed list of returned metrics, making it skimmable. The trailing 'Read-only.' is redundant with annotations and does not earn its place, slightly reducing conciseness.

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 burden of explaining return values, and it does so thoroughly by enumerating all metric categories. Annotations cover safety, params are absent, and the description is complete for a zero-parameter stats tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the schema provides no parameter semantics to document. The description appropriately omits parameter discussion; baseline 4 for zero-param tools 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?

States a specific verb ('Return') and resource ('graph-level metrics for the world model'), and enumerates the metric categories. It does not explicitly differentiate from siblings such as query_world_model or get_cognitive_health, so it falls short of a 5.

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

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

The description only states what metrics are returned; it gives no guidance on when to use this tool versus alternatives like query_world_model or get_cognitive_health. No when-to-use conditions, prerequisites, or exclusions are provided.

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

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

Goes well beyond the annotations by enumerating returned fields, explaining that activity is the last signal received and explicitly warning that activity does not mean availability. It also discloses a side effect the annotations do not imply: passing my_session_id registers that session as active, a state change not reflected in readOnlyHint=true. The disclosure is honest and useful, though the description never reconciles that write-ish side effect with the read-only framing.

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

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

Front-loaded with purpose and the send_message link, then a compact field inventory and a clarifying caveat about activity. Slightly list-heavy, and the Args block is somewhat redundant with the earlier mention of my_session_id, but with no output schema the field enumeration earns its space.

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

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

There is no output schema, and the description compensates by documenting each returned field's meaning and usability (label as `to`, can_message with why_not, active_sessions window). For a one-optional-parameter read tool, an agent has everything needed to call it and interpret results.

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 has 0% schema description coverage (only type string, default ''), so the description carries the full burden and does: it says the parameter is optional, what value to supply (current session ID), and the downstream consequence of supplying it (session registered as active so other sessions can address it). That is meaning beyond anything the schema conveys.

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

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

States a specific verb and resource ('List the agents in the user's workspace') and adds the discriminating scope 'that can be messaged', then names the consumer tool: finding the recipient for send_message. An agent can tell at a glance this is the recipient-discovery step, not a directory dump.

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?

Clear usage context: call this before send_message to find a valid `to` value. It also explains the conditional behavior of passing my_session_id. It does not explicitly say when not to use it (e.g., versus whoami for the caller's own identity), so it stops short of full when/when-not 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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world). The description adds genuinely new behavioral context: results are ordered newest-first only when a time window is supplied, otherwise order is unspecified. That ordering caveat is not derivable from annotations or schema.

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

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

Purpose and the ordering rule are front-loaded, and the Args block is a clean, scannable list with no filler. Slightly long for a simple list tool, but every line carries information.

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

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

With no output schema, a 0%-described schema, and no annotations on ordering/filtering, the description supplies the operationally important facts (pagination, window filtering, ordering) so an agent can call it correctly. It omits what an entity record contains, but that is outside the calling contract.

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 0%, so the description carries the full burden and largely does: it defines page (1-based), size (1-1000), time_range as a named window with examples, since/until as ISO 8601, and the whole-day behavior of a bare date. The only weakness is that time_range's vocabulary is defined only by reference to retrieve_memories, which the agent may not have loaded.

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

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

States a specific verb and resource ("List entities") plus the pagination scope and optional time-window filter, so the agent knows exactly what it returns. It does not, however, name the sibling it differs from (search_entities would be the natural alternative), leaving differentiation implicit.

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 two modes (with/without a window) and their ordering consequences, implying when each is useful, but never states when to prefer this over search_entities or get_entity. Usage is inferred rather than directed.

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 safety profile is covered. The description adds non-obvious behavioral detail beyond that: an unknown status value returns a 422 and the default page size is 50, which helps the agent avoid malformed calls.

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

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

The purpose sentence is front-loaded and the Args block maps cleanly one-to-one to the parameters with no padding. Slightly verbose formatting but every line 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 an output schema present, return values need not be explained, and annotations cover the safety profile; the remaining burden is parameters, which the description documents for all three. Only a mild gap remains around ordering or pagination semantics for skip/limit.

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 0%, so the description carries the full burden, and it does document all three parameters. It is especially valuable for status, enumerating seven valid values and the omission behavior; skip and limit are defined but minimally, drawing on the schema defaults.

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

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

States a specific verb and resource ('List goals') with the optional filter scope made explicit. It is clearly distinguishable from get_goal (single fetch) and create_goal/update_goal by the 'list' verb, but it never names or contrasts with those siblings, so differentiation is left to inference.

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?

'Optionally filtered by status' plus 'Omit for all' implies the when-to-use condition for the filter, which is adequate. There is no guidance on when to prefer this over list_tasks, get_goal, or other listing tools, and no mention of prerequisites.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: the status lifecycle values (proposed, testing, supported, rejected) and the fact that discarded hypotheses are filtered out.

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 resource and the returned fields are front-loaded, and the filter constraint trails as a qualifier. Every clause earns its place.

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

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

With zero parameters and no output schema, the description does the work of indicating what comes back (confidence score and status), which is appropriate compensation. It omits ordering/pagination or volume characteristics, a minor gap for a no-argument list tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes no parameters, so per the rubric the baseline is 4. There is nothing for the description to compensate for on the argument side.

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

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

States a specific verb+resource ('List the hypotheses stored for the user') and describes the returned fields (confidence score, status), which clearly separates it from generate_hypothesis and evaluate_hypothesis by implication. It does not explicitly name the sibling tools, so it stops short of full differentiation.

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

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

Usage is implied — call this to read the user's current hypotheses — and the exclusion of discarded hypotheses hints at scope, but there is no explicit when-to-use guidance or naming of alternatives such as evaluate_hypothesis or generate_hypothesis. Adequate but with a clear gap.

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 safety profile is covered structurally. The description adds two genuinely useful behavioral facts — results are unordered and capped by `limit` — but says nothing about truncation behavior or whether the count is discoverable. With annotations carrying most of the burden, this is adequate but thin.

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 routing sentence is front-loaded and the Args block is conventional and short. Slight redundancy in restating a default that already lives in the schema keeps it off a 5, and the '(unordered)' aside could be folded more tightly into the first clause.

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-optional-parameter list tool with no output schema, the description covers purpose, the alternative sibling, and the bound on results. Nothing essential is missing, though the absence of any note about ordering/pagination semantics beyond the cap 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 0%, so the description must carry `limit` alone — and it does, defining it as 'Maximum number of procedures to return. Default 100.' That fully disambiguates the single parameter, though the repetition of the schema's own default value is the only extra it adds.

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

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

States a specific verb and resource ('List stored procedures') and adds a scope qualifier ('unordered', bounded by `limit`) that an agent can act on. It also names the sibling `match_procedures` as the contrasting tool, so the two can be told apart without opening either schema.

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

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

Explicitly routes the agent away from this tool for task-relevant lookup: 'To find procedures relevant to a task, use `match_procedures`.' That implies this tool's role is raw enumeration, but it never states positively when an agent should want an unfiltered list.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context beyond annotations: a result cap ("Returns up to 100 rules") and the exact returned fields (id, condition, conclusion, domain, confidence weight). It could go further on pagination/ordering for results exceeding 100.

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

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

Front-loaded purpose sentence, then a returns sentence, then a scannable Args block. Structure is clean and each line earns its place, though the Args section is slightly verbose given only two simple params.

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 responsibly summarizes return contents and the 100-rule cap, and both params are documented. For a read-only list tool this is nearly complete; only result ordering and behavior past the 100 cap are unstated.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must carry the full burden, and it does: domain is documented with its empty-string default meaning ("Empty = all domains") and is_active with all three integer values (1/0/-1) and the -1 default. This fully compensates for the undocumented 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 opens with a specific verb+resource ("List stored rules") and states the filtering scope. The resource "rules" is naturally distinct from sibling list_* tools like list_entities, list_goals, list_procedures, but no sibling is named explicitly for differentiation.

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

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

Usage context is implied via the optional filters ("optionally filtered by domain and active status"), and the param docs clarify the semantics of each filter. However, there is no explicit guidance on when to use this over alternatives (e.g., query_world_model, cognitive_query) or 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/non-destructive, so the safety profile is covered. The description adds real behavioral detail beyond them: pagination defaults (25, max 100), a stricter cap under full=True, the fact that oversized results fail rather than truncate, and the default open-task scoping. It does not spell out what a 'summary' row contains beyond the id.

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

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

The purpose sentence is front-loaded and the args block is dense and skimmable, with each entry earning its place. It is longer than strictly necessary but the extra length is functional parameter documentation rather than filler.

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

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

For a six-parameter list tool with no output schema and no annotation-level detail, the description covers filtering, pagination, ordering, output granularity, and the failure mode of full=True. The only gap is the exact composition of a summary row, which the agent must infer.

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 0%, so the description carries the full burden and does: every one of the six params gets meaning, the status enum values are enumerated, source enum values are enumerated with an explanation of 'system', and the interaction between status and include_done is made explicit. This is materially more than the bare schema 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?

States a specific verb+resource and immediately scopes it: 'standalone tasks (work items not tied to a goal plan)', which separates it from goal-plan tasks and agent-task siblings. It also names ordering ('highest priority first'), output shape ('summarized and paginated') and the default filter, so an agent knows exactly what comes back.

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

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

Gives clear operating context: default returns only open statuses, status overrides include_done, and 'full' should only be used for small pages. It also points to the follow-up tools (get_task, update_task, complete_task) that consume the returned ids. It stops short of explicitly routing between this tool and named siblings like get_agent_tasks or get_pending_work.

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 the safety profile (readOnly, idempotent, non-destructive, non-open-world), so the bar is lower. The description nonetheless adds real behavioral depth: the ranking formula (similarity + tag overlap + success rate) and the concrete fallback (without query_text or no close semantic match, only tag-sharing procedures are returned). This edge-case behavior is not derivable from structured fields.

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

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

Front-loaded with the core behavior and ranking, followed by a clean Args block. Sentences are substantive and mostly earn their place, though the trailing args echo the schema names rather than adding entirely new 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?

No output schema exists, yet the description conveys enough about return ordering and fallback so an agent can interpret results. Combined with the annotations, it is complete enough to invoke correctly; only minor input-boundary details are absent.

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 0%, so the description must carry the load, and it does: it documents all three parameters, marks context and query_text as optional, supplies concrete examples for both, and gives the default for limit. It lacks detail on input constraints (e.g. max tags, max limit), but adds substantial meaning beyond the bare schema.

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

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

States a specific verb and resource ('Find stored procedures that fit a task') and specifies the matching mechanism. It's clear it's a smart search/match rather than a plain listing, but it never names the obvious sibling (list_procedures) to sharpen the distinction, so explicit sibling differentiation is missing.

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

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

Usage is implied: use this to locate procedures relevant to a task. The description explains the selection logic (semantic similarity and/or tag overlap), which lets an agent infer when it applies, but it never states when to prefer this over list_procedures or get_procedure, nor when not to use it.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=true; the description adds genuinely new context beyond them — the setting is per-user, defaults to off, and is fully reversible ('can be switched back at any time'). It does not clarify whose 'this user' is (caller vs. target agent) or any permission requirements, keeping it from a 5.

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

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

Purpose and the no-argument read behavior are front-loaded in the first two sentences, which is the right order. There is minor redundancy — 'the setting belongs to the user' overlaps with 'this user's agents', and the Args block restates the single schema property — but nothing is wasted enough to hurt.

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, non-destructive, idempotent toggle with no output schema, the definition covers purpose, default state, reversibility, and the null/omit case. Only the return shape of the no-argument read ('returns it unchanged') is left slightly vague.

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 0%, so the description must carry the burden, and it does: 'accept_from_other_users: True to accept, False to block' plus 'called without an argument, this tool also returns it unchanged' explains the nullable/no-value case. What remains unstated is whether explicit null and an omitted argument behave identically.

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

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

States a specific verb and resource ('change whether agents belonging to other people in the workspace can send messages to this user's agents') and names the sibling it complements (get_messaging_preferences). An agent can tell exactly what this modifies and how it differs from the read-only sibling 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?

Gives explicit routing context: get_messaging_preferences reads the setting, and this tool with no argument also returns it unchanged, establishing when to call it versus the getter. No true exclusion rules are given (e.g. preference between the two ways to read), so it falls 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=false, idempotentHint=true, and destructiveHint=false, so the mutation/safety profile is largely covered. The description still adds real value beyond them: the active-status precondition, the error on invalid status, and the fact that the pause and its reason are written into the goal's history. Reversibility via activate_goal is also disclosed.

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

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

Front-loads the core action and effect, then the precondition, then the reversibility note, then the arg list. No sentence is wasted, though the Args block partly restates parameter semantics already implied by the sentence flow.

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?

An output schema exists, so return values need not be explained. Combined with annotations covering safety and the description covering preconditions, error behavior, history side effects, and the resume path, an agent has everything needed to invoke this 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 0%, so the description carries the burden, and it documents both parameters: goal_id as a UUID of the goal and reason as an optional human-readable reason. That fully maps the two args with type/optionality meaning, though it adds no constraints or examples for reason.

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

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

States a specific verb and resource ('Pause an active goal') plus the effect ('stops being pursued until reactivated'), and explicitly names the counterpart tool activate_goal for resuming. An agent can distinguish this from update_goal, close_goal, and activate_goal without opening any schema.

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

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

Gives an explicit precondition ('Only a goal in active status can be paused'), the failure mode for violating it ('any other status returns an error'), and the follow-up alternative ('Resume it later with activate_goal'). When-to-use, when-not-to-use, and the alternative path are all covered.

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