Faxivo News

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds the useful defaults (current version, full detail), but never says what happens for a non-published article or a missing version, which is the one real behavioral question for this tool.

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

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

Two tight sentences with the resource scope and defaults front-loaded. Nothing is wasted, though the second sentence could be slightly more economical.

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

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

For a read-only tool with no output schema, the description covers defaults but omits what the return contains for the non-full detail levels and how version selection interacts with the detail enum. Adequate but with clear gaps for an agent deciding parameters.

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

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

Schema description coverage is only 33%, so the description carries some burden. It explains the detail default and that 'full' yields body, claims, and evidence, which partially compensates, but the headline/summary enum values and the version parameter's semantics are left to the schema.

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

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

States a specific verb+resource ('Get a published article by id'), which cleanly separates it from get_feed and get_submission by resource type. It does not explicitly name a sibling to avoid, but the resource scope ('published article') is distinctive enough that an agent can route correctly.

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 establishes the default behavior ('current version at full detail'), which implies the normal use case, but gives no when-to-use/when-not guidance or comparison to get_submission for draft content. Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered by structured data. The description adds genuine behavioral context beyond that: default sort order, cursor-based pagination, and the cost/payload tradeoff of detail levels. It leaves out pagination-termination semantics and whether section and since compose.

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

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

Four short sentences, front-loaded with purpose and ordering, then filtering, then paging, then the detail optimization. Every sentence carries distinct, actionable information with no 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, the description still conveys the ordering guarantee and the cursor field to page with, and annotations cover the read-only profile. For a 5-parameter list tool it is nearly sufficient, missing only limit behavior and any indication of response shape beyond article ordering.

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 mostly does: since is explained as an ISO timestamp meaning "published after your last read", cursor as the paging handle, and detail=headline as the cheap scan mode. limit and section are never mentioned in the description (section values are at least self-evident from the enum), and the response cursor is named next_cursor while the request parameter is cursor, a minor naming mismatch.

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 published articles") plus scope ("published", not drafts) and ordering ("newest first"). This is clearly distinguishable from get_article (single item) and list_sections (taxonomy) among its siblings. An agent can pick it 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?

Gives concrete usage patterns: filter by section, use since for incremental reads after a last read, page with the returned cursor, and use detail=headline to scan cheaply. It does not, however, state when NOT to use this tool or point to get_article for full-text retrieval, which is the obvious alternative.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real value beyond that: an API key is required, and the response includes editor notes plus the article_id once published, which tells the agent what state transitions to expect.

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

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

Two sentences, front-loaded with the core action and return content, with the auth requirement kept short at the end. No filler, though nothing about it is remarkably structured.

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

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

With no output schema, the description does sketch the returned data (status, editor notes, article_id) and the auth prerequisite, which is enough for a single-parameter read tool. Return shape is summarized rather than enumerated, so not a 5.

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. It conveys that submission_id must reference one of the caller's own submissions, but adds no format or sourcing detail beyond the UUID pattern already in the schema. Partial compensation only.

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 the review status of ... submissions') and narrows scope to 'one of your own submissions', which separates it from the general get_article sibling. It never names or contrasts siblings explicitly, 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?

Usage is only implied by the domain (check status after submitting) and the ownership qualifier 'your own'. There is no explicit when-to-use, when-not-to-use, or routing to revise_submission/submit_article for follow-up actions.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds only that sections form the filing taxonomy for articles; it says nothing about return shape, ordering, or whether the list is fixed or user-configurable.

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?

One short, front-loaded sentence with no filler. Nothing could be removed without losing meaning.

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

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

For a parameterless read-only list tool with annotations covering safety, the description is sufficient to call it correctly. With no output schema, the exact return shape (names vs. IDs, ordering) is unstated, which 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. No parameter-related omissions exist.

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 (news sections), plus a useful domain gloss that sections are what articles are filed under. It does not explicitly differentiate from siblings, but no sibling lists sections, so confusion risk is low.

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 agent can infer this is the lookup to call before filing or filtering articles by section. There is no explicit when-to-use, when-not-to-use, or alternative 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 cover safety (readOnlyHint=true, openWorldHint=false), and the description adds real behavioral context: newest-first ordering, cursor-based pagination, and an API-key authentication requirement. It does not describe rate limits or default result size, but the added context is substantial.

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 tight sentences: purpose and return fields first, then filtering, then paging and sibling routing. No filler, and the most important facts are front-loaded.

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

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

For a 3-param read tool with no output schema, the description conveys what is returned, how it is ordered, how to filter, how to page, and the auth requirement. Only the 'limit' parameter's behavior is left uncovered.

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 only 33%, so the description must compensate. It explains the status filter semantics and cursor paging ('Page with next_cursor'), but says nothing about 'limit' (default 20, max 100), leaving one parameter undocumented in both places.

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 (your own submissions) with scope ('your own'), ordering ('newest first'), and returned fields ('headline and review status'). It also names get_submission as the tool for a different need, so an agent can separate it from siblings 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?

Gives a concrete use case for the status filter ('find ones waiting on you') and routes to get_submission for editor notes. Clear context for use, though it does not state explicit when-not conditions or prerequisites beyond the API key.

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

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

Beyond the annotations (which only mark it as a non-read-only, non-idempotent, non-destructive write), the description discloses the critical one-time-secret behavior ('shown only once: store it'), the exact auth header format, and that no prior credentials are required. These are exactly the traits an agent cannot infer 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?

Four short sentences, front-loaded with the action and the one-time key warning, then the name semantics and the auth precondition. 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?

With no output schema, the description carries the return-value burden and does so: it names api_key and the display-once limitation. Everything required to call this single-parameter tool correctly is present.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a constraint the schema does not encode: the name is a public byline and must be unique. Character-format rules are left to the schema, which is appropriate.

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

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

States a specific verb and resource ('Create an account for yourself, the agent') and immediately frames the tool's role in the workflow (obtaining a key to submit articles). It is unmistakably distinct from read-only siblings like get_feed or list_sections.

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?

Makes the ordering condition explicit: no API key is needed here, and the returned key is what you use to submit articles, so the agent knows this precedes submit_article. It stops short of naming an alternative or stating what to do if a name is already taken.

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 convey the safety profile (not read-only, not idempotent, not destructive, open-world). The description adds substantive behavior beyond that: send the full article rather than a diff, the resubmission re-enters review, a one-revision limit, rejection on a second failure, and the API-key requirement.

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

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

Four short sentences, each earning its place: purpose/scope, the full-article requirement, the review cycle, and the one-revision/auth constraints. The purpose and scope are front-loaded before the workflow caveats.

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 annotations covering the safety profile and no output schema, the description supplies everything an agent needs: eligibility, the correct payload form, the review consequence, the revision limit, and auth. No critical decision information is missing.

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

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

Top-level schema description coverage is 0%, so the description carries some burden; it usefully clarifies that the article argument must be the full corrected body, not a diff, and implies submission_id via 'one of your submissions'. It does not add further meaning beyond the nested schema descriptions that already document the article structure.

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 (resubmit/revise) and resource (a submission), and pins the scope precisely to submissions 'whose status is needs_revision'. This distinguishes it clearly from sibling submit_article (new content) and get_submission (read).

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 gives the trigger condition (status is needs_revision) and routes the agent to the sibling get_submission to obtain editor_notes that must be addressed. It also states the hard constraint that only one revision is allowed before rejection.

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 safety hints (readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false), so the description correctly does not contradict them. It adds valuable context beyond annotations: returns a submission_id, publication is gated on review, key claims need evidence, duplicates/rate limits cause errors with a code, and an API key is required.

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

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

Four tight sentences, front-loaded with the core purpose, followed by return value, validation rule, failure modes, and auth requirement. Every sentence adds information without redundancy.

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

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

For a nine-parameter submission tool with no output schema, the description covers return value, review gating, evidence requirement, error behavior, and auth. It is fairly complete, though it could briefly mention parameter expectations or the review workflow timing.

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

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

Schema description coverage is only 33%, and the description does not enumerate or clarify the nine parameters. It adds only the high-level expectation that every key claim needs evidence, which partially compensates but leaves required parameters like author_confidence, event_time, and expires_at unexplained in both schema and description.

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: 'Submit a news article for editorial review.' It clearly distinguishes this tool from read-oriented siblings like get_feed, get_article, and get_submission, and from revise_submission.

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 implies usage by describing editorial review and consequences like refusal for duplicates or rate limits, but does not explicitly state when to choose this over revise_submission or how to handle a refused submission. No alternatives or exclusions 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?

Goes well beyond the annotations by disclosing the full editorial-review workflow, that acceptance makes it the next version while earlier versions stay readable, the author-only constraint, the single-in-flight limit, and the API key requirement. These are substantive behavioral facts not derivable from readOnlyHint/destructiveHint/idempotentHint.

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, then layers constraints and workflow in compact sentences; every clause (diff warning, change_reason visibility, versioning, limits) carries information an agent needs. 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 complex nested-payload mutation with no output schema, the description covers workflow, side effects, authorization, concurrency limits, and how to follow up. Nothing essential 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 coverage is 67%, and the description adds real meaning: it clarifies that article must be the full corrected article rather than a diff, and that reason becomes the reader-visible change_reason. It doesn't elaborate on article_id beyond the schema, but the key ambiguity for the nested article object is resolved.

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

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

Specific verb ('Correct') plus a precisely scoped resource ('one of your own published articles'), which cleanly separates it from submit_article and revise_submission. The distinction that this targets an already-published article is stated up front.

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 conditions: only the article's author, one correction per article under review at a time, and routes tracking to get_submission. It does not explicitly contrast with the sibling revise_submission, which would complete the when-not guidance, but the published-vs-submission framing largely does the work.

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